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'."
class parameters.Parameters(registry)
component_list_type = 'parameters'

The component list type will be used to look up possible implementations of the component type via entry points (entry points provide a list of components, so it should be plural). Set both component_type and component_list_type to None if module doesn’t have components.

component_type = 'parameter'

The component type for components of this module. This will be used to look for macros (they are defined singularly, and should not be plural). Set both component_type and component_list_type to None if module doesn’t have components.

gen_xml(xml_parent, data)

Update the XML element tree based on YAML data. Override this method to add elements to the XML output. Create new Element objects and add them to the xml_parent. The YAML data structure must not be modified.

:arg class:xml.etree.ElementTree xml_parent: the parent XML element :arg dict data: the YAML data structure

sequence = 21

The sequence number for the module. Modules are invoked in the order of their sequence number in order to produce consistently ordered XML output.

active-choices()

Active Choices Parameter

Requires the Jenkins Active Choices Plug-in.

Parameters:

  • name (str) – Name of the parameter (required).

  • description (str) – Description of the parameter.

  • script (list) –

    Use a Groovy script to define the parameter.

    Parameter:

    • groovy (str) Groovy DSL Script

    • use-groovy-sandbox (bool) To run this

      Groovy script in a sandbox with limited abilities (default True)

    • script-additional-classpath (list) Additional

      classpath entries accessible from the script.

  • fallback-script (list) –

    Use a Fallback script. If the script (specified above) fails, the fallback script will be used as a fallback.

    Parameter:

    • groovy (str) Groovy DSL Script

    • use-groovy-sandbox (bool) To run this Groovy

      script in a sandbox with limited abilities. (default True)

    • script-additional-classpath (list) Additional

      classpath entries accessible from the script.

  • enable-filters (bool) – If enabled a text box will appear next to this element and will permit the user to filter its entries. The list values never get re-evaluated (default False).

  • filter-starts-at (int) – How many characters a user must enter before the filter is applied (default 1).

  • choice-type (str) –

    type of the choices. (default ‘single-select’)

    Allowed Values:

    • single-select

    • multi-select

    • radio-buttons

    • checkboxes

Minimal Example:

- job:
    name: active-choices-job
    parameters:
      - active-choices:
          name: lorem

Full Example:

- job:
    name: active-choices-job
    parameters:
      - active-choices:
          name: lorem
          description: ipsum
          script:
              groovy: |-
                  return [
                      'param1',
                      'param2'
                  ]
              use-groovy-sandbox: false
              script-additional-classpath:
                  - file:/jar-file-path
                  - file:/jar-file-path2
          fallback-script:
              groovy: |-
                  return [
                      'param3',
                      'param4'
                  ]
              use-groovy-sandbox: false
              script-additional-classpath:
                  - file:/jar-file-path
                  - file:/jar-file-path2
          choice-type: multi-select
          enable-filters: true
          filter-starts-at: 1
active-choices-reactive()

Active Choices Reactive Parameter

Requires the Jenkins Active Choices Plug-in.

Parameters:

  • name (str) – Name of the parameter (required).

  • description (str) – Description of the parameter.

  • script (list) –

    Use a Groovy script to define the parameter.

    Parameter:

    • groovy (str) Groovy DSL Script

    • use-groovy-sandbox (bool) To run this

      Groovy script in a sandbox with limited abilities (default True)

    • script-additional-classpath (list) Additional

      classpath entries accessible from the script.

  • fallback-script (list) –

    Use a Fallback script. If the script (specified above) fails, the fallback script will be used as a fallback.

    Parameter:

    • groovy (str) Groovy DSL Script

    • use-groovy-sandbox (bool) To run this Groovy

      script in a sandbox with limited abilities. (default True)

    • script-additional-classpath (list) Additional

      classpath entries accessible from the script.

  • enable-filters (bool) – If enabled a text box will appear next to this element and will permit the user to filter its entries. The list values never get re-evaluated (default False).

  • filter-starts-at (int) – How many characters a user must enter before the filter is applied (default 1).

  • choice-type (str) –

    type of the choices. (default ‘single-select’)

    Allowed Values:

    • single-select

    • multi-select

    • radio-buttons

    • checkboxes

  • referenced-parameters (str) – Comma separated list of other job parameters referenced in the uno-choice script

Minimal Example:

- job:
    name: active-choices-job
    parameters:
      - active-choices-reactive:
          name: foo

Full Example:

- job:
    name: active-choices-job
    parameters:
      - active-choices-reactive:
          name: lorem
          description: ipsum
          script:
              groovy: |-
                  return [
                      'param1',
                      'param2'
                  ]
              use-groovy-sandbox: false
              script-additional-classpath:
                  - file:/jar-file-path
                  - file:/jar-file-path2
          fallback-script:
              groovy: |-
                  return [
                      'param3',
                      'param4'
                  ]
              use-groovy-sandbox: false
              script-additional-classpath:
                  - file:/jar-file-path
                  - file:/jar-file-path2
          choice-type: multi-select
          enable-filters: true
          filter-starts-at: 1
          referenced-parameters: foo,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 (str) – default credentials ID (optional)

  • description (str) – a description of the parameter (optional)

Example:

parameters:
  - credentials:
      name: OS_CREDENTIALS
      type: usernamepassword
      default: "default-credentials-id"
      description: "Test credentials"
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-reference()

Active Choices Reactive Reference Parameter

Requires the Jenkins Active Choices Plug-in.

Parameters:

  • name (str) – Name of the parameter (required).

  • description (str) – Description of the parameter.

  • script (list) –

    Use a Groovy script to define the parameter.

    Parameter:

    • groovy (str) Groovy DSL Script

    • use-groovy-sandbox (bool) To run this

      Groovy script in a sandbox with limited abilities (default True)

    • script-additional-classpath (list) Additional

      classpath entries accessible from the script.

  • fallback-script (list) –

    Use a Fallback script. If the script (specified above) fails, the fallback script will be used as a fallback.

    Parameter:

    • groovy (str) Groovy DSL Script

    • use-groovy-sandbox (bool) To run this Groovy

      script in a sandbox with limited abilities. (default True)

    • script-additional-classpath (list) Additional

      classpath entries accessible from the script.

  • omit-value-field (bool) – By default Dynamic Reference Parameters always include a hidden input for the value. If your script creates an input HTML element, you can check this option and the value input field will be omitted (default False).

  • referenced-parameters (str) – Comma separated list of other job parameters referenced in the uno-choice script. When any of the referenced parameters are updated, the Groovy script will re-evaluate the choice list using the updated values of referenced parameters.

  • choice-type (str) –

    type of the choices. (default ‘input-text-box’)

    Allowed Values:

    • input-text-box

    • numbered-list

    • bullet-items-list

    • formatted-html

    • formatted-hidden-html

Minimal Example:

- job:
    name: dynamic-reference-job
    parameters:
      - dynamic-reference:
          name: lorem

Full Example:

- job:
    name: dynamic-reference-job
    folder: unochoice
    parameters:
      - dynamic-reference:
          name: lorem
          description: ipsum
          script:
              groovy: |-
                  return [
                      'param1',
                      'param2'
                  ]
              use-groovy-sandbox: false
              script-additional-classpath:
                  - file:/path
                  - file:/path2
          fallback-script:
              groovy: |-
                  return [
                      'param3',
                      'param4'
                  ]
              use-groovy-sandbox: false
              script-additional-classpath:
                  - file:/path
                  - file:/path2
          choice-type: numbered-list
          omit-value-field: True
          referenced-parameters: dolor
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, multi-level-single-select, multi-level-multi-select, radio, checkbox, textbox, json (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 (optional, default ‘,’)

  • groovy-script (str) – the groovy script contents (optional, default ‘,’)

  • groovy-script-file (str) – location of groovy script file to generate parameters (optional, default ‘’)

  • bindings (str) – variable bindings for the groovy script (optional, default ‘’)

  • classpath (str) – the classpath for the groovy script (optional, default ‘,’)

  • default-groovy-script (str) – the default groovy script contents (optional, default ‘’)

  • default-groovy-classpath (str) – the default classpath for the groovy script (optional, default ‘’)

  • description-groovy-script (str) – location of groovy script when value description needs to come from a groovy script (optional, default ‘’)

  • description-groovy-script-file (str) – location of groovy script file when value description needs to come from a groovy script (optional, default ‘’)

  • description-groovy-classpath (str) – classpath for the value description groovy script (optional, default ‘’)

  • javascript (str) – the javascript script contents (optional, default ‘’)

  • javascript-file (str) – location of javasript script file to generate parameters (optional, default ‘’)

  • save-json-parameter-to-file (bool) – if json parameter should be saved to file (optional, default False)

Minimal Example:

parameters:
  - extended-choice:
      name: OPTIONS
      description: "Available options"
      type: 'PT_CHECKBOX'
      value: OptionA,OptionB,OptionC

Full Example:

parameters:
  - extended-choice:
      name: OPTIONS_VALUE
      description: "Available options"
      property-key: key
      quote-value: true
      type: multi-select
      value: "foo|bar|select"
      visible-items: 2
      multi-select-delimiter: '|'
      default-value: foo
      default-property-key: fookey
  - extended-choice:
      name: OPTIONS_FILE
      description: "Available options"
      property-file: /home/foo/property.prop
      property-key: key
      quote-value: true
      type: multi-select
      visible-items: 2
      multi-select-delimiter: '|'
      default-property-file: /home/property.prop
      default-property-key: fookey
  - extended-choice:
      name: OPTIONS_CHECKBOX
      type: checkbox
      value: !join:
        - ','
        -
            - OptionA
            - OptionB
            - OptionC
      visible-items: 2
  - extended-choice:
      name: MULTISELECTOPTIONS
      description: "Available options"
      property-key: key
      quote-value: true
      type: multi-select
      value: !join:
        - '|'
        -
            - foo
            - bar
            - select
      visible-items: 2
      multi-select-delimiter: '|'
      default-value: foo
  - extended-choice:
      name: JSON
      type: json
      groovy-script: >-
          import net.sf.json.JSONObject;
          def jsonEditorOptions = JSONObject.fromObject(/{schema:
          {"type": "object", "title": "Name", "properties":
          {"name": {"type": "string", "propertyOrder" : 1}}}}/);
  - extended-choice:
      name: MULTILEVELMULTISELECT
      type: multi-level-multi-select
      value: !join:
          - ','
          -
              - foo
              - bar
              - baz
  - extended-choice:
      name: MULTILEVELSINGLESELECT
      type: multi-level-single-select
      value: foo
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."
git-parameter()

This parameter allows you to select a git tag, branch or revision number as parameter in Parametrized builds.

Requires the Jenkins Git Parameter Plugin.

Parameters:

  • name (str) – Name of the parameter

  • description (str) – Description of the parameter (default ‘’)

  • type (str) –

    The type of the list of parameters (default ‘PT_TAG’)

    Allowed Values:
    • PT_TAG list of all commit tags in repository -

      returns Tag Name

    • PT_BRANCH list of all branches in repository -

      returns Branch Name

    • PT_BRANCH_TAG list of all commit tags and all

      branches in repository - returns Tag Name or Branch Name

    • PT_REVISION list of all revision sha1 in repository

      followed by its author and date - returns Tag SHA1

    • PT_PULL_REQUEST

  • branch (str) – Name of branch to look in. Used only if listing revisions. (default ‘’)

  • branchFilter (str) – Regex used to filter displayed branches. If blank, the filter will default to “.*”. Remote branches will be listed with the remote name first. E.g., “origin/master” (default ‘.*’)

  • tagFilter (str) – Regex used to filter displayed branches. If blank, the filter will default to “.*”. Remote branches will be listed with the remote name first. E.g., “origin/master” (default ‘*’)

  • sortMode (str) –

    Mode of sorting. (default ‘NONE’)

    Allowed Values:

    • NONE

    • DESCENDING

    • ASCENDING

    • ASCENDING_SMART

    • DESCENDING_SMART

  • defaultValue (str) – This value is returned when list is empty. (default ‘’)

  • selectedValue (str) –

    Which value is selected, after loaded parameters. If you choose ‘default’, but default value is not present on the list, nothing is selected. (default ‘NONE’)

    Allowed Values:

    • NONE

    • TOP

    • DEFAULT

  • useRepository (str) – If in the task is defined multiple repositories parameter specifies which the repository is taken into account. If the parameter is not defined, is taken first defined repository. The parameter is a regular expression which is compared with a URL repository. (default ‘’)

  • quickFilterEnabled (bool) – When this option is enabled will show a text field. Parameter is filtered on the fly. (default false)

Minimal Example:

parameters:
  - git-parameter:
      name: Foo

Full Example:

parameters:
  - git-parameter:
      name: Foo
      description: Lorem ipsum dolor sit amet.
      type: PT_BRANCH_TAG
      branch: baz
      tagFilter: bam
      branchFilter: boo
      sortMode: ASCENDING
      defaultValue: bor
      selectedValue: TOP
      useRepository: buh
      quickFilterEnabled: true
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)

  • all-nodes (bool) – to run job on all nodes matching label in parallel (default: false)

  • matching-label (str) – to run all nodes matching label ‘success’, ‘unstable’ or ‘allCases’ (optional)

  • node-eligibility (str) – all nodes, ignore temporary nodes or ignore temporary offline nodes (optional, default all nodes)

Example:

parameters:
  - label:
      name: EXAMPLE LABEL 1
      description: "EXAMPLE LABEL DESCRIPTION 1"
      matching-label: "success"
      node-eligibility: "all"
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
parameter-separator()

A parameter separator.

Parameters:

  • name (str) – name of the separator (default “”, the plugin will assign a randomly generated UUID if not specified)

  • separator-style (str) – the style of the separator. Uses CSS. (default “”)

  • section-header-text (str) – the section header text of the separator (default “”)

  • section-header-style (str) – the section header style (CSS) of the separator. Uses CSS. (default “”)

Example:

parameters:
  - parameter-separator:
      name: lorem
      separator-style: FOO
      section-header: bar
      section-header-style: font-weight:bold;z-index:10000
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."
persistent-bool()

A persistent boolean parameter.

Requires the Jenkins Persistent 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)

  • successfulOnly (bool) – if true, then the value of the parameter gets persisted only between successful builds (optional, default: false)

Example:

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

A persistent single selection parameter.

Requires the Jenkins Persistent Parameter Plugin.

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)

  • successfulOnly (bool) – if true, then the value of the parameter gets persisted only between successful builds (optional, default: false)

Example:

parameters:
  - persistent-choice:
      name: project
      choices:
        - nova
        - glance
      description: "On which project to run?"
      successfulOnly: false
persistent-string()

A persistent string parameter.

Requires the Jenkins Persistent 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)

  • trim (bool) – strip whitespaces from the begnning and end of the string (optional, default: false)

  • successfulOnly (bool) – if true, then the value of the parameter gets persisted only between successful builds (optional, default: false)

Example:

parameters:
  - persistent-string:
      name: FOO
      default: bar
      description: "A parameter named FOO, defaults to 'bar'."
      trim: false
      successfulOnly: false
persistent-text()

A persistent text parameter.

Requires the Jenkins Persistent 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)

  • trim (bool) – strip whitespaces from the begnning and end of the string (optional, default: false)

  • successfulOnly (bool) – if true, then the value of the parameter gets persisted only between successful builds (optional, default: false)

Example:

parameters:
  - persistent-text:
      name: FOO
      default: bar
      description: "A persistent parameter named FOO, defaults to 'bar'."
      successfulOnly: false
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)

  • trim (bool) – strip whitespaces from the begnning and end of the string (optional, default: false)

Example:

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

A svn tag parameter

Requires the Jenkins Parameterized Trigger Plugin.

Parameters:

  • name (str) – the name of the parameter

  • url (str) – the url to list tags from

  • credentials-id (str) – Credentials ID to use for authentication (default ‘’)

  • filter (str) – the regular expression to filter tags (default ‘’)

  • default (str) – the default value of the parameter (default ‘’)

  • description (str) – a description of the parameter (default ‘’)

  • max-tags (int) – the number of tags to display (default ‘100’)

  • sort-newest-first (bool) – sort tags from newest to oldest (default true)

  • sort-z-to-a (bool) – sort tags in reverse alphabetical order (default false)

Example:

parameters:
  - svn-tags:
      name: BRANCH_NAME
      default: release
      description: A parameter named BRANCH_NAME default is release
      url: http://svn.example.org/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