Jenkins Pipeline Parameters

External

• https://wiki.jenkins.io/display/JENKINS/Parameterized+Build
• https://jenkins.io/doc/book/pipeline/jenkinsfile/#handling-parameters

Internal

• Jenkins Concepts
• Jenkins Pipeline Syntax

Overview

A parameter is a way to configure a pipeline. If you think of a pipeline as a function, then a parameter is the function's argument. When a parameterized build is in the queue, attempting to start another build of the same project will only succeed if the parameter values are different, or if the Execute concurrent builds if necessary option is enabled.

Parameter Declaration

A parameter is declared in the pipeline's Jenkinsfile with a different syntax depending on whether the pipeline is declarative or scripted. If the pipeline was configured to accept parameters using "Build with Parameters" option, once the Jenkinsfile is committed to the repository, the Jenkins server monitoring the branch will automatically update the UI based on the new Jenkinsfile, making the parameter available in the UI. For more details see Relationship between the Pipeline UI and Jenkinsfile Parameters below. As such, a parameter enables the pipeline to prompt the user for a piece of information to be passed into the build.

Each parameter has a name and a value, which depends on the parameter type. A default value and a description can be specified when the parameter is declared. Each parameter should have a unique name. Spaces are not permitted in parameter names.

Declarative Pipeline Paramenter Declaration

Declarative pipelines support parameters by default, with the parameters directive.

Scripted Pipeline Paramenter Declaration

properties([

  parameters([

    string(
        name: 'POD_MEMORY_LIMIT_Gi',
        defaultValue: '8', 
        description: 'The pod\'s cgroups memory limit, in Gi')

  ])
])

Accessing Parameters

The parameters configured as described above are accessible as members of the params variable throughout the Jenkinsfile:

...
echo "pod memory limit: ${params.POD_MEMORY_LIMIT_Gi}"

params.paramName is equivalent with params.get(paramName).

The name-value pairs will also be exported as environment variables when the build starts, allowing subsequent parts of the build configuration, such as build steps, to access those values using the following syntax:

${POD_MEMORY_LIMIT_Gi}

Relationship Between the Pipeline UI and Jenkinsfile Parameters

If the pipeline was configured to accept parameters using "Build with Parameters" option, once a parameter is defined in Jenkinsfile, and the Jenkinsfile committed to the repository on a specific branch, the multi-branch pipeline that tracks the branch automatically updates the pipeline UI for that branch, so the parameter become available in "Build with Parameters" associated with the branch.

When the build is parameterized, the "Build Now" control is replaced by "Build with Parameters", which allows the user the option to specify values for each defined parameter. If they choose not to do anything, the build will start with the "Default Value". If the build is started automatically, the "Default Value" is used, unless the build triggering function provides the corresponding values, as follows:

build(
  job: "IntegrationTesting",
  parameters: [
    string(name: 'branch', value: serverSha),
    string(name: 'branchName', value: branch)
  ] + artifacts.keySet().sort().collect({ name ->
          echo "name: ${name}, value: ${artifacts[name]['artifact']}"
          string(name: name, value: artifacts[name]['artifact'])
    }),
    quietPeriod: 0,
    wait: true,
    propagate: true
)

Relationship Between UI and Jenkinsfile Parameters

• TODO_nw3td What is the relationship between the parameters declared in the pipeline's UI and the parameters declared in the pipleline's Jenkinsfile?
• TODO_n88Y6 Establish the precedence between a defaultValue declared in the "parameter" section in Jenkinsfile and one declared for the same parameter in the UI. It seems the file value influences the UI value.