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.

Parameterized Build

If the pipeline was configured at creation time with "This project is parameterized", it designates a "parameterized build", meaning that the build UI exposes the "Build with Parameters" option. Alternatively, if "This project is parameterized" is not selected, the build UI will expose "Build Now" option, which does not give the choice of parameters.

For a parameterized build, 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')

  ])
])

Multi-line description:

properties([
  parameters([
    string(
        name: 'something'
        description: """
    This is a 
    multi-line
    description
    """.stripIndent()
  ])
])

Parameters Types

https://jenkins.io/doc/pipeline/steps/pipeline-input-step/

String

properties([
  parameters([
    string(
        name: 'COLOR',
        defaultValue: 'blue', 
        description: 'Some color')
  ])
])

Accessing Parameters

In Jenkinsfile

The name-value pairs are 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}

The parameters are also accessible as members of the params variable throughout the Jenkinsfile (params.paramName is equivalent with params.get(paramName)):

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

Jenkinsfile Groovy code can only access parameters using the params.paramName form and not as environment variables.

In Groovy Code

TODO, so far the parameters were passed into Groovy code as arguments of constructors and function calls form Jenkinsfile.