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
- 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'
-
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.
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.
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."
-
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"
-
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