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

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

Parameters:

• name (str) – the name of the parameter
• description (str) – a description of the parameter (optional)
• type (str) – parameter select type. Can be PT_SINGLE_SELECT, PT_MULTI_SELECT, PT_RADIO, PT_CHECKBOX, PT_TEXTBOX
• value (str) – comma separated list of values
• visible-item-count (str) – number of lines to render for multi-select (default 5)
• multi-select-delimiter (str) – value between selections when the parameter is a multi-select (default ,)
• default-value (str) – default selected value

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"

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

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