Properties

The Properties module supplies a wide range of options that are implemented as Jenkins job properties.

Component: properties
Macro:property
Entry Point:jenkins_jobs.properties

Example:

job:
  name: test_job

  properties:
    - github:
        url: https://github.com/openstack-infra/jenkins-job-builder/
authenticated-build

Specifies an authorization matrix where only authenticated users may trigger a build.

Deprecated since version 0.1.0.: Please use authorization.

Example:

properties:
  - authenticated-build
authorization

Specifies an authorization matrix

Parameters:<name> (list) –
<name> is the name of the group or user, containing
the list of rights to grant.
<name> rights:
  • credentials-create
  • credentials-delete
  • credentials-manage-domains
  • credentials-update
  • credentials-view
  • job-build
  • job-cancel
  • job-configure
  • job-delete
  • job-discover
  • job-extended-read
  • job-move
  • job-read
  • job-status
  • job-workspace
  • ownership-jobs
  • run-delete
  • run-replay
  • run-update
  • scm-tag

Example:

properties:
    - authorization:
        admin:
            - credentials-create
            - credentials-delete
            - credentials-manage-domains
            - credentials-update
            - credentials-view
            - job-build
            - job-cancel
            - job-configure
            - job-delete
            - job-discover
            - job-move
            - job-read
            - job-status
            - job-workspace
            - ownership-jobs
            - run-delete
            - run-replay
            - run-update
            - scm-tag
        anonymous:
            - job-read
            - job-extended-read
batch-tasks

Batch tasks can be tasks for events like releases, integration, archiving, etc. In this way, anyone in the project team can execute them in a way that leaves a record.

A batch task consists of a shell script and a name. When you execute a build, the shell script gets run on the workspace, just like a build. Batch tasks and builds “lock” the workspace, so when one of those activities is in progress, all the others will block in the queue.

Requires the Jenkins Batch Task Plugin.

Parameters:batch-tasks (list) –

Batch tasks.

Tasks:
  • name (str) Task name.
  • script (str) Task script.

Example:

properties:
  - batch-tasks:
      - name: release
        script: mvn -B release:prepare release:perform
      - name: say hello
        script: echo "Hello world"
branch-api

Enforces a minimum time between builds based on the desired maximum rate. Requires the Jenkins Branch API Plugin.

Parameters:
  • number-of-builds (int) – The maximum number of builds allowed within the specified time period. (default 1)
  • time-period (str) –

    The time period within which the maximum number of builds will be enforced. (default ‘Hour’)

    valid values:Hour, Day, Week, Month, Year
  • skip-rate-limit (bool) – Permit user triggered builds to skip the rate limit (default false)

Minimal Example:

properties:
  - branch-api

Full example:

properties:
  - branch-api:
      time-period: Day
      number-of-builds: 5
      skip-rate-limit: true
build-blocker

This plugin keeps the actual job in the queue if at least one name of currently running jobs is matching with one of the given regular expressions.

Requires the Jenkins Build Blocker Plugin.

Parameters:
  • use-build-blocker (bool) – Enable or disable build blocker (default true)
  • blocking-jobs (list) – One regular expression per line to select blocking jobs by their names (required)
  • block-level (str) – block build globally (‘GLOBAL’) or per node (‘NODE’) (default ‘GLOBAL’)
  • queue-scanning (str) – scan build queue for all builds (‘ALL’) or only buildable builds (‘BUILDABLE’) (default ‘DISABLED’)

Example:

Minimal Example:

properties:
  - build-blocker:
      blocking-jobs:
        - ".*-deploy"

Full Example:

properties:
  - build-blocker:
      use-build-blocker: true
      blocking-jobs:
        - ".*-deploy"
        - "^maintenance.*"
      block-level: 'NODE'
      queue-scanning: 'BUILDABLE'
build-discarder
Parameters:
  • days-to-keep (int) – Number of days to keep builds for (default -1)
  • num-to-keep (int) – Number of builds to keep (default -1)
  • artifact-days-to-keep (int) – Number of days to keep builds with artifacts (default -1)
  • artifact-num-to-keep (int) – Number of builds with artifacts to keep (default -1)

Example:

properties:
    - build-discarder:
        days-to-keep: 42
        num-to-keep: 43
        artifact-days-to-keep: 44
        artifact-num-to-keep: 45
properties:
    - build-discarder
builds-chain-fingerprinter

Builds chain fingerprinter. Requires the Jenkins Builds chain fingerprinter Plugin.

Parameters:
  • per-builds-chain (bool) – enable builds hierarchy fingerprinting (default false)
  • per-job-chain (bool) – enable jobs hierarchy fingerprinting (default false)

Example:

properties:
  - builds-chain-fingerprinter:
      per-builds-chain: true
      per-job-chain: true
cachet-gating

The Cachet Gating Plugin provides a gating mechanism based on the availability of resources.

Requires the Jenkins: Cachet Gate Plugin.

Parameters:
  • required-resources (bool) – Confirm availability of listed resources before building. Requires the list of resources to also be defined. (default true)
  • resources (list) – which resources to gate

Example:

properties:
      - cachet-gating:
          required-resources: true
          resources:
              - beaker
              - brew
copyartifact

Specify a list of projects that have access to copy the artifacts of this project.

Requires the Jenkins Copy Artifact plugin.

Parameters:projects (str) – comma separated list of projects that can copy artifacts of this project. Wild card character ‘*’ is available.

Example:

properties:
  - copyartifact:
      projects: foo*
delivery-pipeline

Requires the Jenkins Delivery Pipeline Plugin.

Parameters:
  • stage (str) – Name of the stage for this job (default ‘’)
  • task (str) – Name of the task for this job (default ‘’)
  • description (str) – task description template for this job (default ‘’)

Minimal Example:

properties:
  - delivery-pipeline

Full Example:

properties:
  - delivery-pipeline:
      stage: Stage
      task: Task
      description: Task-Description
disable-resume

Do not allow the pipeline to resume if the master restarts Requires the Jenkins Pipeline Job Plugin.

Example:

properties:
  - disable-resume
disk-usage

Enables the Disk Usage Plugin. Requires the Jenkins Disk Usage Plugin.

Example:

properties:
  - disk-usage
docker-container

Requires the Jenkins: Docker Plugin.

Parameters:
  • docker-registry-url (str) – URL of the Docker registry. (default ‘’)
  • credentials-id (str) – Credentials Id for the Docker registey. (default ‘’)
  • commit-on-success (bool) – When a job completes, the docker slave instance is committed with repository based on the job name and build number as tag. (default false)
  • additional-tag (str) – Additional tag to apply to the docker slave instance when committing it. (default ‘’)
  • push-on-success (bool) – Also push the resulting image when committing the docker slave instance. (default false)
  • clean-local-images (bool) – Clean images from the local daemon after building. (default true)

Minimal Example:

properties:
  - docker-container

Full Example:

properties:
  - docker-container:
      commit-on-success: true
      additional-tag: latest
      push-on-success: true
      clean-local-images: true
      docker-registry-url: https://index.docker.io/v1/
      credentials-id: 71e4f29c-162b-40d0-85d9-3ddfba2911a0
gitbucket

Integrate GitBucket to Jenkins. Requires the Jenkins GitBucket Plugin.

Parameters:
  • url (str) – GitBucket URL to issue (required)
  • link-enabled (bool) – Enable hyperlink to issue (default false)

Minimal Example:

properties:
  - gitbucket:
      url: https://foo.com

Full Example:

properties:
  - gitbucket:
      url: https://foo.com
      link-enabled: true
github

Sets the GitHub URL for the project.

Parameters:
  • url (str) – the GitHub URL (required)
  • display-name (str) – This value will be used as context name for commit status if status builder or status publisher is defined for this project. (>= 1.14.1) (default ‘’)

Minimal Example:

properties:
  - github:
      url: https://github.com/openstack-infra/jenkins-job-builder/

Full Example:

properties:
  - github:
      url: https://github.com/openstack-infra/jenkins-job-builder/
      display-name: foo
gitlab

Sets the GitLab connection for the project. Configured via Jenkins Global Configuration. Requires the Jenkins GitLab Plugin.

Parameters:connection (str) – the GitLab connection name (required)

Example:

properties:
  - gitlab:
      connection: gitlab-connection

Configures the GitLab-Logo Plugin. Requires the Jenkins GitLab Logo Plugin.

Parameters:repository-name (str) – the GitLab repository name (required)

Example:

properties:
  - gitlab-logo:
      repository-name: gitlab-repository-name
groovy-label

This plugin allows you to use Groovy script to restrict where this project can be run.

Requires the Jenkins Groovy Label Assignment Plugin.

Return value from Groovy script is treated as Label Expression. It is treated as followings:

  • A non-string value will be converted to a string using toString()
  • When null or blank string is returned, node restriction does not take effect (or is not overwritten).
  • When exception occurred or Label Expression is not parsed correctly, builds are canceled.
Parameters:
  • script (str) – Groovy script (default ‘’)
  • sandbox (bool) – Use Groovy Sandbox. (default false) If checked, run this Groovy script in a sandbox with limited abilities. If unchecked, and you are not a Jenkins administrator, you will need to wait for an administrator to approve the script
  • classpath (list) – Additional classpath entries accessible from the script, each of which should be an absolute local path or URL to a JAR file, according to “The file URI Scheme” (optional)

Minimal Example:

properties:
    - groovy-label

Full Example:

properties:
    - groovy-label:
        script: "$LABEL_NAME"
        sandbox: true
        classpath:
            - "file:/minimal/absolute/path/to/file.jar"
            - "file:///traditional/absolute/path/to/file.jar"
            - "http://example.org/path/to/file.jar"
            - "https://example.org/path/to/file.jar"
heavy-job

This plugin allows you to define “weight” on each job, and making each job consume that many executors

Requires the Jenkins Heavy Job Plugin.

Parameters:weight (int) – Specify the total number of executors that this job should occupy (default 1)

Example:

properties:
  - heavy-job:
      weight: 2
inject

Allows you to inject environment variables into the build. Requires the Jenkins Env Inject Plugin.

Parameters:
  • properties-file (str) – file to read with properties (optional)
  • properties-content (str) – key=value properties (optional)
  • script-file (str) – file with script to run (optional)
  • script-content (str) – script to run (optional)
  • groovy-content (str) – groovy script to run (optional)
  • groovy-sandbox (bool) – run groovy script in sandbox (default false)
  • load-from-master (bool) – load files from master (default false)
  • enabled (bool) – injection enabled (default true)
  • keep-system-variables (bool) – keep system variables (default true)
  • keep-build-variables (bool) – keep build variable (default true)
  • override-build-parameters (bool) – override build parameters (default false)

Example:

properties:
  - inject:
      properties-content: |
        FOO=bar
        BAZ=foobar
least-load

Enables the Least Load Plugin. Requires the Jenkins Least Load Plugin.

Parameters:disabled (bool) – whether or not leastload is disabled (default true)

Example:

properties:
  - least-load:
      disabled: False
lockable-resources

Requires the Jenkins Lockable Resources Plugin.

Parameters:
  • resources (str) – List of required resources, space separated. (required, mutual exclusive with label)
  • label (str) – If you have created a pool of resources, i.e. a label, you can take it into use here. The build will select the resource(s) from the pool that includes all resources sharing the given label. (required, mutual exclusive with resources)
  • var-name (str) – Name for the Jenkins variable to store the reserved resources in. Leave empty to disable. (default ‘’)
  • number (int) – Number of resources to request, empty value or 0 means all. This is useful, if you have a pool of similar resources, from which you want one or more to be reserved. (default 0)
  • match-script (str) – Groovy script to reserve resource based on its properties. Leave empty to disable. (default None)
  • groovy-sandbox (bool) – Execute the provided match-script in Groovy sandbox. Leave empty to disable. (default False)

Example:

---
properties:
  - lockable-resources:
      resources: "the-resource"
---
properties:
  - lockable-resources:
      label: "pool-1"
---
properties:
  - lockable-resources:
      resources: "the-resource"
      var-name: "RESOURCE_NAME"
      number: 10
---
properties:
  - lockable-resources:
      match-script: "resourceName == MY_VAR"
      groovy-sandbox: true
ownership

Plugin provides explicit ownership for jobs and slave nodes. Requires the Jenkins Ownership Plugin.

Parameters:
  • enabled (bool) – whether ownership enabled (default : true)
  • owner (str) – the owner of job
  • co-owners (list) – list of job co-owners

Example:

properties:
 - ownership:
    owner: foo
    co-owners:
     - bar
     - moo
priority-sorter

Allows simple ordering of builds, using a configurable job priority.

Requires the Jenkins Priority Sorter Plugin.

Parameters:priority (int) – Priority of the job. Higher value means higher priority, with 3 as the default priority. (required)

Example:

properties:
  - priority-sorter:
      priority: 3
promoted-build

Marks a build for promotion. A promotion process with an identical name must be created via the web interface in the job in order for the job promotion to persist. Promotion processes themselves cannot be configured by jenkins-jobs due to the separate storage of plugin configuration files. Requires the Jenkins Promoted Builds Plugin.

Parameters:names (list) – the promoted build names (optional)

Example:

properties:
  - promoted-build:
      names:
        - "Release to QA"
        - "Jane Must Approve"
rebuild

This plug-in allows the user to rebuild a parameterized build without entering the parameters again.It will also allow the user to edit the parameters before rebuilding. Requires the Jenkins Rebuild Plugin.

Parameters:
  • auto-rebuild (bool) – Rebuild without asking for parameters (default false)
  • rebuild-disabled (bool) – Disable rebuilding for this job (default false)

Minimal Example:

properties:
    - rebuild

Full Example:

properties:
    - rebuild:
        auto-rebuild: true
        rebuild-disabled: true
sidebar

Allows you to add links in the sidebar. Requires the Jenkins Sidebar-Link Plugin.

Parameters:
  • url (str) – url to link to (optional)
  • text (str) – text for the link (optional)
  • icon (str) – path to icon (optional)

Example:

properties:
   - sidebar:
       url: https://jenkins.debian.net/userContent/about.html
       text: About jenkins.debian.net
       icon: /userContent/images/debian-swirl-24x24.png
   - sidebar:
       url: https://jenkins.debian.net/view/reproducible
       text: reproducible builds jobs
       icon: /userContent/images/debian-jenkins-24x24.png
slack

Requires the Jenkins Slack Plugin

When using Slack Plugin version < 2.0, Slack Plugin itself requires a publisher aswell as properties please note that you have to add the publisher to your job configuration aswell. When using Slack Plugin version >= 2.0, you should only configure the publisher.

Parameters:
  • notify-start (bool) – Send notification when the job starts (default false)
  • notify-success (bool) – Send notification on success. (default false)
  • notify-aborted (bool) – Send notification when job is aborted. ( default false)
  • notify-not-built (bool) – Send notification when job set to NOT_BUILT status. (default false)
  • notify-unstable (bool) – Send notification when job becomes unstable. (default false)
  • notify-failure (bool) – Send notification when job fails. (default false)
  • notify-back-to-normal (bool) – Send notification when job is succeeding again after being unstable or failed. (default false)
  • 'notify-repeated-failure' (bool) – Send notification when job is still failing after last failure. (default false)
  • include-test-summary (bool) – Include the test summary. (default False)
  • include-custom-message (bool) – Include a custom message into the notification. (default false)
  • custom-message (str) – Custom message to be included. (default ‘’)
  • room (str) – A comma separated list of rooms / channels to send the notifications to. (default ‘’)

Example:

properties:
    - slack:
        room: dummy, dummy2
        notify-start: true
        notify-success: true
slave-prerequisites

This plugin allows you to check prerequisites on slave before a job can run a build on it

Requires the Jenkins Slave Prerequisites Plugin.

Parameters:
  • script (str) – A script to be executed on slave node. If returning non 0 status, the node will be vetoed from hosting the build. (required)
  • interpreter (str) – Command line interpreter to be used for executing the prerequisite script - either shell for Unix shell or cmd for Windows batch script. (default shell)

Example:

properties:
  - slave-prerequisites:
      script: |
        #!/bin/bash
        AVAILABLE=$(df -BG --output=avail / | tail -1)
        test ${AVAILABLE%G} -ge 10
properties:
  - slave-prerequisites:
      interpreter: cmd
      script: |
        @echo off
        if exist C:\Jenkins\workspace.lock exit /b 1
slave-utilization

This plugin allows you to specify the percentage of a slave’s capacity a job wants to use.

Requires the Jenkins Slave Utilization Plugin.

Parameters:
  • slave-percentage (int) – Specify the percentage of a slave’s execution slots that this job should occupy (default 0)
  • single-instance-per-slave (bool) – Control whether concurrent instances of this job will be permitted to run in parallel on a single slave (default false)

Example:

properties:
  - slave-utilization:
      slave-percentage: 40
      single-instance-per-slave: false
throttle

Throttles the number of builds for this job. Requires the Jenkins Throttle Concurrent Builds Plugin.

Parameters:
  • option (str) – throttle project (throttle the project alone) or category (throttle the project as part of one or more categories)
  • max-per-node (int) – max concurrent builds per node (default 0)
  • max-total (int) – max concurrent builds (default 0)
  • enabled (bool) – whether throttling is enabled (default true)
  • categories (list) – multiproject throttle categories
  • matrix-builds (bool) – throttle matrix master builds (default true)
  • matrix-configs (bool) – throttle matrix config builds (default false)
  • parameters-limit (str) – prevent jobs with matching parameters from running concurrently (default false)
  • parameters-check-list (list) – Comma-separated list of parameters to use when comparing jobs (optional)

Example:

properties:
  - throttle:
      max-per-node: 2
      max-total: 4
      categories:
        - cat1
        - cat2
      option: category
      matrix-builds: false
      matrix-configs: true
zeromq-event

This is a Jenkins plugin that will publish Jenkins Job run events (start, complete, finish) to a ZMQ PUB socket.

Requires the Jenkins ZMQ Event Publisher.

Example:

properties:
  - zeromq-event