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?"
-
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 ‘’)
- 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 ‘’)
- 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"
-
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-nodes (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."
-
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'."
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