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

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'

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

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

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

groovy-label¶

This plugin allows 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)
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)

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

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 (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 seperated 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 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)

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

Properties¶

Previous topic

Next topic

This Page