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

Example:

properties:
  - authenticated-build
authorization

Specifies an authorization matrix

The available rights are:
job-delete job-configure job-read job-extended-read job-discover job-build job-workspace job-cancel run-delete run-update scm-tag

Example:

properties:
  - authorization:
      admin:
        - job-delete
        - job-configure
        - job-read
        - job-discover
        - job-build
        - job-workspace
        - job-cancel
        - run-delete
        - run-update
        - scm-tag
      anonymous:
        - job-discover
        - 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.

Task:
  • 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"
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:

properties:
  - build-blocker:
      use-build-blocker: true
      blocking-jobs:
        - ".*-deploy"
        - "^maintenance.*"
      block_level: 'GLOBAL'
      queue-scanning: 'BUILDABLE'
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
copyartifact

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

Requires the Jenkins Copy Artifact plugin.

Parameters:projects (string) – 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:
  • description (str) – task description template for this job (default: ‘’)
  • stage (str) – Name of the stage for this job (default: ‘’)
  • task (str) – Name of the task for this job (default: ‘’)

Example:

properties:
  - delivery-pipeline:
      stage: Stage
      task: Task
      description: Task-Description
extended-choice

Use of this config option is deprecated. You should use the extended-choice option in the parameter section of the job configuration instead.

github

Sets the GitHub URL for the project.

Parameters:url (str) – the GitHub URL

Example:

properties:
  - github:
      url: https://github.com/openstack-infra/jenkins-job-builder/
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)
  • 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
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 100 as the standard priority. (required)

Example:

properties:
  - priority-sorter:
      priority: 150
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

Example:

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

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)

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
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:
  • 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)
  • option (str) – throttle project or category
  • categories (list) – multiproject throttle categories

Example:

properties:
  - throttle:
      max-total: 4
      categories:
        - cat1
        - cat2
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