README.md

File Parameters Plugin

Introduction

Offers alternative types of file parameter that are compatible with Pipeline and do not suffer from the architectural flaws of the type built into Jenkins core.

See JENKINS-27413 and JENKINS-29289 for background.

Minimal usage

Base64 file parameter

If you defined a Base64 file parameter named FILE in the GUI configuration for a Pipeline project, you can access it in a couple of ways - as a Base64-encoded environment variable:

node {
    sh 'echo $FILE | base64 -d'
}

Or via a temporary file with the decoded content:

node {
    withFileParameter('FILE') {
        sh 'cat $FILE'
    }
}

Stashed file parameter

A stashed file parameter can also be accessed in a couple of ways - as a stash of the same name with a single file of the same name:

node {
    unstash 'FILE'
    sh 'cat FILE'
}

Or via a temporary file:

node {
    withFileParameter('FILE') {
        sh 'cat $FILE'
    }
}

Accessing original upload filename

Original filename will be stored in evironment in <parameter_name>_FILENAME variable - assuming parameter is named FILE, snippet below will give you file with original filename in current workspace:

node {
  unstash 'FILE'
  sh 'mv FILE $FILE_FILENAME'
}

Usage in Declarative Pipeline

You can now declare and use file parameters via Declarative Pipeline syntax:

pipeline {
  agent any
  parameters {
    base64File 'small'
    stashedFile 'large'
  }
  stages {
    stage('Example') {
      steps {
        withFileParameter('small') {
          sh 'cat $small'
        }
        unstash 'large'
        sh 'cat large'
      }
    }
  }
}

Usage with input

You can use Base64 parameters for uploading small files in the middle of the build:

def fb64 = input message: 'upload', parameters: [base64File('file')]
node {
    withEnv(["fb64=$fb64"]) {
        sh 'echo $fb64 | base64 -d'
    }
}

Currently there is no mechanism for doing this with stashed files. Nor can you use the withFileParameter wrapper here.

Usage with build

You can use Base64 parameters for passing small files to downstream builds:

build job: 'downstream', parameters: [base64File(name: 'file', base64: Base64.encoder.encodeToString('hello'.bytes)))]

Usage with HTTP API

You can pass file parameters to the HTTP API (in the Jenkins UI, this HTTP API is also referred to as “REST API”):

Curl example:

curl -u $auth -F FILE=@/tmp/f $jenkins/job/myjob/buildWithParameters

Javascript example:

const file = fileInput.files[0]; // a File object
const body = new FormData();
body.append('FILE', file); // will come through to the job as the named file parameter 'FILE'
const request = new Request(`${jobUrl}buildWithParameters`, { method: 'POST', body });
fetch(request); // omitted, API token and other credentials

LICENSE

Licensed under MIT, see LICENSE