File Parameter


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

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:

node {
    sh 'echo $FILE | base64 -d'
    withFileParameter('FILE') {
        sh 'cat $FILE'

That is: as a Base64-encoded environment variable; or via a temporary file with the decoded content.

A stashed file parameter can also be accessed in a couple of ways:

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

That is: as a stash of the same name with a single file of the same name; or, again, via a temporary file.

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


Licensed under MIT, see LICENSE