Jenkins Pipeline Parameters: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
Line 1: Line 1:
=External=
* https://wiki.jenkins.io/display/JENKINS/Parameterized+Build
* https://jenkins.io/doc/book/pipeline/jenkinsfile/#handling-parameters
=Internal=
=Internal=


* [[Jenkins_Concepts#Pipeline_Parameters|Jenkins Concepts]]
* [[Jenkins_Concepts#Pipeline_Parameters|Jenkins Concepts]]
* [[Jenkins_Pipeline_Syntax#Parameters|Jenkins Pipeline Syntax]]
* [[Jenkins_Pipeline_Syntax#Parameters|Jenkins Pipeline Syntax]]
=Overview=
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" can be specified. The name-value pairs will 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:
${PARAMETER_NAME}
The parameter values can also be retrieved in a Jenkinsfile with the following syntax:
<syntaxhighlight lang='groovy'>
properties([
  ...
  parameters([
    string(
      name: 'branch',
      defaultValue: 'develop',
      description: 'Branch name or branch head\' SHA1 hash to be used to run this build on.'
    ),
    string(
      name: 'artifact version',
      description: 'The version of the artifact (ex: 1.0.0-build.1)'
    ),
    text(
      name: 'Test Packages,
      defaultValue: 'test-package-1',
    )
])
])
</syntaxhighlight>
They can be reported, for debugging purposes, as follows:
<syntaxhighlight lang='groovy'>
params.get(propertyName)
</syntaxhighlight>
Each parameter should have a unique name. Spaces are not permitted in parameter names.
When the build is parameterized, the "Build Now" control will be replaced with "Build with Parameters", where users will be prompted 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:
<syntaxhighlight lang='groovy'>
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
)
</syntaxhighlight>
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.
====TODO====
<font color=darkgray>
TODO:
* <span id='TODO_nw3td'></span>TODO_nw3td What is the relationship between the parameters declared in the pipeline's UI and the parameters declared in the pipleline's Jenkinsfile?
* <span id='TODO_n88Y6'></span>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.
</font>
==Parameters Types==
===String===
===Multi-Line String Parameter===
===File Parameter===

Revision as of 22:55, 17 April 2020

External

Internal

Overview

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" can be specified. The name-value pairs will 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:

${PARAMETER_NAME}

The parameter values can also be retrieved in a Jenkinsfile with the following syntax:

properties([
  ...
  parameters([
    string(
      name: 'branch',
      defaultValue: 'develop',
      description: 'Branch name or branch head\' SHA1 hash to be used to run this build on.'
    ),
    string(
      name: 'artifact version',
      description: 'The version of the artifact (ex: 1.0.0-build.1)'
    ),
    text(
      name: 'Test Packages,
      defaultValue: 'test-package-1',
    )
 ])
])

They can be reported, for debugging purposes, as follows:

params.get(propertyName)

Each parameter should have a unique name. Spaces are not permitted in parameter names.

When the build is parameterized, the "Build Now" control will be replaced with "Build with Parameters", where users will be prompted 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
)

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.

TODO

TODO:

  • 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.

Parameters Types

String

Multi-Line String Parameter

File Parameter