Parameters

The Parameters module allows you to specify build parameters for a job.

Component: parameters
Macro:parameter
Entry Point:jenkins_jobs.parameters

Example:

job:
  name: test_job

  parameters:
    - string:
        name: FOO
        default: bar
        description: "A parameter named FOO, defaults to 'bar'."
bool

A boolean parameter.

Parameters:
  • name (str) – the name of the parameter
  • default (str) – the default value of the parameter (optional)
  • description (str) – a description of the parameter (optional)

Example:

parameters:
  - bool:
      name: FOO
      default: false
      description: "A parameter named FOO, defaults to 'false'."
choice

A single selection parameter.

Parameters:
  • name (str) – the name of the parameter
  • choices (list) – the available choices, first one is the default one.
  • description (str) – a description of the parameter (optional)

Example:

parameters:
  - choice:
      name: project
      choices:
        - nova
        - glance
      description: "On which project to run?"
copyartifact-build-selector

Control via a build parameter, which build the copyartifact plugin should copy when it is configured to use ‘build-param’. Requires the Jenkins Copy Artifact plugin.

Parameters:
  • name (str) – name of the build parameter to store the selection in
  • description (str) – a description of the parameter (optional)
  • which-build (str) – which to provide as the default value in the UI. See which-build param of copyartifact from the builders module for the available values as well as options available that control additional behaviour for the selected value.

Example:

parameters:
  - copyartifact-build-selector:
      name: BUILD_SELECTOR
      which-build: workspace-latest
      description: 'Which build from upstream to copy artifacts from'
credentials

A credentials selection parameter. Requires the Jenkins Credentials Plugin.

Parameters:
  • name (str) – the name of the parameter
  • type (str) –

    credential type (optional, default ‘any’)

    Allowed Values:
    • any Any credential type (default)
    • usernamepassword Username with password
    • sshkey SSH Username with private key
    • secretfile Secret file
    • secrettext Secret text
    • certificate Certificate
  • required (bool) – whether this parameter is required (optional, default false)
  • default (string) – default credentials ID (optional)
  • description (str) – a description of the parameter (optional)

Example:

.. literalinclude::        /../../tests/parameters/fixtures/credentials-param001.yaml
language:yaml
dynamic-choice

Dynamic Choice Parameter Requires the Jenkins Jenkins Dynamic Parameter Plug-in.

Parameters:
  • name (str) – the name of the parameter
  • description (str) – a description of the parameter (optional)
  • script (str) – Groovy expression which generates the potential choices.
  • remote (bool) – the script will be executed on the slave where the build is started (default false)
  • classpath (str) – class path for script (optional)
  • read-only (bool) – user can’t modify parameter once populated (default false)

Example:

parameters:
  - dynamic-choice:
      name: OPTIONS
      description: "Available options"
      script: "['optionA', 'optionB']"
      remote: false
      read-only: false
dynamic-choice-scriptler

Dynamic Choice Parameter (Scriptler) Requires the Jenkins Jenkins Dynamic Parameter Plug-in.

Parameters:
  • name (str) – the name of the parameter
  • description (str) – a description of the parameter (optional)
  • script-id (str) – Groovy script which generates the default value
  • parameters (list) –

    parameters to corresponding script

    Parameter:
    • name (str) Parameter name
    • value (str) Parameter value
  • remote (bool) – the script will be executed on the slave where the build is started (default false)
  • read-only (bool) – user can’t modify parameter once populated (default false)

Example:

parameters:
  - dynamic-choice-scriptler:
      name: OPTIONS
      description: "Available options"
      script-id: "scriptid.groovy"
      parameters:
        - name: param1
          value: value1
        - name: param2
          value: value2
      remote: false
      read-only: false
dynamic-string

Dynamic Parameter Requires the Jenkins Jenkins Dynamic Parameter Plug-in.

Parameters:
  • name (str) – the name of the parameter
  • description (str) – a description of the parameter (optional)
  • script (str) – Groovy expression which generates the potential choices
  • remote (bool) – the script will be executed on the slave where the build is started (default false)
  • classpath (str) – class path for script (optional)
  • read-only (bool) – user can’t modify parameter once populated (default false)

Example:

parameters:
  - dynamic-string:
      name: FOO
      description: "A parameter named FOO, defaults to 'bar'."
      script: "bar"
      remote: false
      read-only: false
dynamic-string-scriptler

Dynamic Parameter (Scriptler) Requires the Jenkins Jenkins Dynamic Parameter Plug-in.

Parameters:
  • name (str) – the name of the parameter
  • description (str) – a description of the parameter (optional)
  • script-id (str) – Groovy script which generates the default value
  • parameters (list) –

    parameters to corresponding script

    Parameter:
    • name (str) Parameter name
    • value (str) Parameter value
  • remote (bool) – the script will be executed on the slave where the build is started (default false)
  • read-only (bool) – user can’t modify parameter once populated (default false)

Example:

parameters:
  - dynamic-string-scriptler:
      name: FOO
      description: "A parameter named FOO, defaults to 'bar'."
      script-id: "scriptid.groovy"
      parameters:
        - name: param1
          value: value1
        - name: param2
          value: value2
      remote: false
      read-only: false
extended-choice

Creates an extended choice parameter where values can be read from a file Requires the Jenkins Extended Choice Parameter Plugin.

Parameters:
  • name (str) – name of the parameter
  • description (str) – description of the parameter (optional, default ‘’)
  • property-file (str) – location of property file to read from (optional, default ‘’)
  • property-key (str) – key for the property-file (optional, default ‘’)
  • quote-value (bool) – whether to put quotes around the property when passing to Jenkins (optional, default false)
  • visible-items (str) – number of items to show in the list (optional, default 5)
  • type (str) – type of select, can be single-select, multi-select, radio, checkbox or textbox (optional, default single-select)
  • value (str) – comma separated list of values for the single select or multi-select box (optional, default ‘’)
  • default-value (str) – used to set the initial selection of the single-select or multi-select box (optional, default ‘’)
  • value-description (str) – comma separated list of value descriptions for the single select or multi-select box (optional, default ‘’)
  • default-property-file (str) – location of property file when default value needs to come from a property file (optional, default ‘’)
  • default-property-key (str) – key for the default property file (optional, default ‘’)
  • description-property-file (str) – location of property file when value description needs to come from a property file (optional, default ‘’)
  • description-property-key (str) – key for the value description property file (optional, default ‘’)
  • multi-select-delimiter (str) – value between selections when the parameter is a multi-select (optiona, default ‘,’)

Example:

parameters:
  - extended-choice:
      name: OPTIONS
      description: "Available options"
      type: 'PT_CHECKBOX'
      value: OptionA,OptionB,OptionC
      visible-item-count: "2"
file

A file parameter.

Parameters:
  • name (str) – the target location for the file upload
  • description (str) – a description of the parameter (optional)

Example:

parameters:
  - file:
      name: test.txt
      description: "Upload test.txt."
hidden

Allows you to use parameters hidden from the build with parameter page. Requires the Jenkins Hidden Parameter Plugin.

Parameters:
  • name (str) – the name of the parameter
  • default (str) – the default value of the parameter (optional)
  • description (str) – a description of the parameter (optional)

Example:

parameters:
  - hidden:
      name: FOO
      default: bar
      description: A parameter named FOO, defaults to 'bar'
label

A node label parameter.

Parameters:
  • name (str) – the name of the parameter
  • default (str) – the default value of the parameter (optional)
  • description (str) – a description of the parameter (optional)

Example:

parameters:
  - label:
      name: node
      default: precise
      description: "The node on which to run the job"
matrix-combinations

Matrix combinations parameter Requires the Jenkins Matrix Combinations Plugin.

Parameters:
  • name (str) – the name of the parameter
  • description (str) – a description of the parameter (optional)
  • filter (str) – Groovy expression to use filter the combination by default (optional)

Example:

parameters:
  - matrix-combinations:
      name: FOO
      description: "Select matrix combinations"
      filter: "platform == foo"
maven-metadata

This parameter allows the resolution of maven artifact versions by contacting the repository and reading the maven-metadata.xml. Requires the Jenkins Maven Metadata Plugin.

Parameters:
  • name (str) – Name of the parameter
  • description (str) – Description of the parameter (optional)
  • repository-base-url (str) – URL from where you retrieve your artifacts (default ‘’)
  • repository-username (str) – Repository’s username if authentication is required. (default ‘’)
  • repository-password (str) – Repository’s password if authentication is required. (default ‘’)
  • artifact-group-id (str) – Unique project identifier (default ‘’)
  • artifact-id (str) – Name of the artifact without version (default ‘’)
  • packaging (str) – Artifact packaging option. Could be something such as jar, zip, pom.... (default ‘’)
  • versions-filter (str) – Specify a regular expression which will be used to filter the versions which are actually displayed when triggering a new build. (default ‘’)
  • default-value (str) – For features such as SVN polling a default value is required. If job will only be started manually, this field is not necessary. (default ‘’)
  • maximum-versions-to-display (str) – The maximum number of versions to display in the drop-down. Any non-number value as well as 0 or negative values will default to all. (default 10)
  • sorting-order (str) – ascending or descending (default descending)

Example:

parameters:
  - maven-metadata:
      name: 'maven metadata param'
      repository-base-url: 'http://nexus.example.com'
      repository-username: 'username'
      repository-password: 'password'
      artifact-group-id: 'com.example'
      artifact-id: 'example'
      packaging: 'jar'
      versions-filter: '[0-9]+'
      default-value: 'FIRST'
      maximum-versions-to-display: "5"
      sorting-order: "Ascending"
node

Defines a list of nodes where this job could potentially be executed on. Restrict where this project can be run, If your using a node or label parameter to run your job on a particular node, you should not use the option “Restrict where this project can be run” in the job configuration - it will not have any effect to the selection of your node anymore!

Parameters:
  • name (str) – the name of the parameter
  • description (str) – a description of the parameter (optional)
  • default-slaves (list) – The nodes used when job gets triggered by anything else other than manually
  • allowed-slaves (list) – The nodes available for selection when job gets triggered manually. Empty means ‘All’.
  • ignore-offline-nodes (bool) – Ignore nodes not online or not having executors (default false)
  • allowed-multiselect (bool) – Allow multi node selection for concurrent builds - this option only makes sense (and must be selected!) in case the job is configured with: “Execute concurrent builds if necessary”. With this configuration the build will be executed on all the selected nodes in parallel. (default false)

Example:

parameters:
  - node:
      name: SLAVE_NAME
      description: "Select slave"
      allowed-slaves:
        - slave001
        - slave002
        - slave003
      ignore-offline-nodes: true
      allowed-multiselect: true
password

A password parameter.

Parameters:
  • name (str) – the name of the parameter
  • default (str) – the default value of the parameter (optional)
  • description (str) – a description of the parameter (optional)

Example:

parameters:
  - password:
      name: FOO
      default: 1HSC0Ts6E161FysGf+e1xasgsHkgleLh09JUTYnipPvw=
      description: "A parameter named FOO."
promoted build

A promoted build parameter. Requires the Jenkins Promoted Builds Plugin.

Parameters:
  • name (str) – the name of the parameter (required)
  • project-name (str) – the job from which the user can pick runs (required)
  • promotion-name (str) – promotion process to choose from (optional)
  • description (str) – a description of the parameter (optional)

Example:

parameters:
  - promoted:
      name: FOO
      project-name: "foo-build"
      promotion-name: "passed-promotion"
      description: "Select a foo-build for promotion"
random-string

This parameter generates a random string and passes it to the build, preventing Jenkins from combining queued builds. Requires the Jenkins Random String Parameter Plugin.

Parameters:
  • name (str) – Name of the parameter
  • description (str) – Description of the parameter (default ‘’)
  • failed-validation-message (str) – Failure message to display for invalid input (default ‘’)

Example:

parameters:
  - random-string:
      name: job-string
      description: "A random string passed to the job"
      failed-validation-message: "Your input string is invalid"
run

A run parameter.

Parameters:
  • name (str) – the name of the parameter
  • project-name (str) – the name of job from which the user can pick runs
  • description (str) – a description of the parameter (optional)

Example:

parameters:
  - run:
      name: FOO
      project-name: "foo-build"
      description: "Select a foo-build for promotion"
string

A string parameter.

Parameters:
  • name (str) – the name of the parameter
  • default (str) – the default value of the parameter (optional)
  • description (str) – a description of the parameter (optional)

Example:

parameters:
  - string:
      name: FOO
      default: bar
      description: "A parameter named FOO, defaults to 'bar'."
svn-tags

A svn tag parameter Requires the Jenkins Parameterized Trigger Plugin.

Parameters:
  • name (str) – the name of the parameter
  • default (str) – the default value of the parameter (optional)
  • description (str) – a description of the parameter (optional)
  • url (str) – the url to list tags from
  • filter (str) – the regular expression to filter tags

Example:

parameters:
  - svn-tags:
      name: BRANCH_NAME
      default: release
      description: A parameter named BRANCH_NAME default is release
      url: http://svn.example.com/repo
      filter: [A-za-z0-9]*
text

A text parameter.

Parameters:
  • name (str) – the name of the parameter
  • default (str) – the default value of the parameter (optional)
  • description (str) – a description of the parameter (optional)

Example:

parameters:
  - text:
      name: FOO
      default: bar
      description: "A parameter named FOO, defaults to 'bar'."
validating-string

A validating string parameter Requires the Jenkins Validating String Plugin.

Parameters:
  • name (str) – the name of the parameter
  • default (str) – the default value of the parameter (optional)
  • description (str) – a description of the parameter (optional)
  • regex (str) – a regular expression to validate the string
  • msg (str) – a message to display upon failed validation

Example:

parameters:
  - validating-string:
      name: FOO
      default: bar
      description: "A parameter named FOO, defaults to 'bar'."
      regex: [A-Za-z]*
      msg: Your entered value failed validation