Builders

Builders define actions that the Jenkins job should execute. Examples include shell scripts or maven targets. The builders attribute in the Job definition accepts a list of builders to invoke. They may be components defined below, locally defined macros (using the top level definition of builder:, or locally defined components found via the jenkins_jobs.builders entry point.

Component: builders
Macro:builder
Entry Point:jenkins_jobs.builders

Example:

job:
  name: test_job

  builders:
    - shell: "make test"
ant

Execute an ant target. Requires the Jenkins Ant Plugin.

To setup this builder you can either reference the list of targets or use named parameters. Below is a description of both forms:

1) Listing targets:

After the ant directive, simply pass as argument a space separated list of targets to build.

Parameter:space separated list of Ant targets

Example to call two Ant targets:

builders:
  - ant: "target1 target2"

The build file would be whatever the Jenkins Ant Plugin is set to use per default (i.e build.xml in the workspace root).

2) Using named parameters:

Parameters:
  • targets (str) – the space separated list of ANT targets.
  • buildfile (str) – the path to the ANT build file.
  • properties (list) – Passed to ant script using -Dkey=value (optional)
  • ant-name (str) – the name of the ant installation, (default ‘default’) (optional)
  • java-opts (str) – java options for ant, can have multiples, must be in quotes (optional)

Example specifying the build file too and several targets:

builders:
  - ant:
     targets: "debug test install"
     buildfile: "build.xml"
     properties:
        builddir: "/tmp/"
        failonerror: true
     java-opts:
        - "-ea"
        - "-Xmx512m"
     ant-name: "Standard Ant"
artifact-resolver

Allows one to resolve artifacts from a maven repository like nexus (without having maven installed) Requires the Jenkins Repository Connector Plugin

Parameters:
  • fail-on-error (bool) – Whether to fail the build on error (default false)
  • repository-logging (bool) – Enable repository logging (default false)
  • target-directory (str) – Where to resolve artifacts to
  • artifacts (list) –

    list of artifacts to resolve

    Artifact:
    • group-id (str) – Group ID of the artifact
    • artifact-id (str) – Artifact ID of the artifact
    • version (str) – Version of the artifact
    • classifier (str) – Classifier of the artifact (default ‘’)
    • extension (str) – Extension of the artifact (default ‘jar’)
    • target-file-name (str) – What to name the artifact (default ‘’)

Example:

builders:
  - artifact-resolver:
      fail-on-error: true
      repository-logging: true
      target-directory: foo
      artifacts:
        - group-id: commons-logging
          artifact-id: commons-logging
          version: "1.1"
          classifier: src
          extension: jar
          target-file-name: comm-log.jar
        - group-id: commons-lang
          artifact-id: commons-lang
          version: "1.2"
batch

Execute a batch command.

Parameter:the batch command to execute

Example:

builders:
  - batch: "foo/foo.bat"
builders-from

Use builders from another project. Requires the Jenkins Template Project Plugin.

Parameters:projectName (str) – the name of the other project

Example:

builders:
  - builders-from: "base-build"
change-assembly-version

Change the assembly version. Requires the Jenkins Change Assembly Version.

Parameters:
  • version (str) – Set the new version number for replace (default 1.0.0)
  • assemblyFile (str) – The file name to search (default AssemblyInfo.cs)

Example:

builders:
  - change-assembly-version:
        version: "1.2.3"
        assembly-file: "AFile"
conditional-step

Conditionally execute some build steps. Requires the Jenkins Conditional BuildStep Plugin.

Depending on the number of declared steps, a Conditional step (single) or a Conditional steps (multiple) is created in Jenkins.

Parameters:
  • condition-kind (str) – Condition kind that must be verified before the steps are executed. Valid values and their additional attributes are described in the conditions table.
  • on-evaluation-failure (str) – What should be the outcome of the build if the evaluation of the condition fails. Possible values are fail, mark-unstable, run-and-mark-unstable, run and dont-run. Default is fail.
  • steps (list) – List of steps to run if the condition is verified. Items in the list can be any builder known by Jenkins Job Builder.
Condition kind Description
always Condition is always verified
never Condition is never verified
boolean-expression

Run the step if the expression expends to a representation of true

condition-expression:
 Expression to expand
current-status

Run the build step if the current build status is within the configured range

condition-worst:
 Accepted values are SUCCESS, UNSTABLE, FAILURE, NOT_BUILD, ABORTED
condition-best:Accepted values are SUCCESS, UNSTABLE, FAILURE, NOT_BUILD, ABORTED
shell

Run the step if the shell command succeed

condition-command:
 Shell command to execute
windows-shell

Similar to shell, except that commands will be executed by cmd, under Windows

condition-command:
 Command to execute
file-exists

Run the step if a file exists

condition-filename:
 Check existence of this file
condition-basedir:
 If condition-filename is relative, it will be considered relative to either workspace, artifact-directory, or jenkins-home. Default is workspace.

Example:

builders:
      - conditional-step:
          condition-kind: current-status
          condition-worst: SUCCESS
          condition-best: FAILURE
          steps:
              - shell: "sl"
copyartifact

Copy artifact from another project. Requires the Jenkins Copy Artifact plugin.

Parameters:
  • project (str) – Project to copy from
  • filter (str) – what files to copy
  • target (str) – Target base directory for copy, blank means use workspace
  • flatten (bool) – Flatten directories (default: false)
  • optional (bool) – If the artifact is missing (for any reason) and optional is true, the build won’t fail because of this builder (default: false)
  • which-build (str) – which build to get artifacts from (optional, default last-successful)
  • build-number (str) – specifies the build number to get when when specific-build is specified as which-build
  • permalink (str) – specifies the permalink to get when permalink is specified as which-build
  • stable (bool) – specifies to get only last stable build when last-successful is specified as which-build
  • fallback-to-last-successful (bool) – specifies to fallback to last successful build when upstream-build is specified as which-build
  • param (string) – specifies to use a build parameter to get the build when build-param is specified as which-build
  • parameter-filters (string) – Filter matching jobs based on these parameters (optional)
Which-build values:
 
  • last-successful
  • specific-build
  • last-saved
  • upstream-build
  • permalink
  • workspace-latest
  • build-param
Permalink values:
 
  • last
  • last-stable
  • last-successful
  • last-failed
  • last-unstable
  • last-unsuccessful

Example:

builders:
  - copyartifact:
      project: foo
      filter: "*.tar.gz"
      target: /home/foo
      which-build: specific-build
      build-number: "123"
      optional: true
      flatten: true
      parameter-filters: PUBLISH=true
critical-block-end

Designate the end of a critical block. Must be used in conjuction with critical-block-start.

Must also add a build wrapper (exclusion), specifying the resources that control the critical block. Otherwise, this will have no effect.

Requires Jenkins Exclusion Plugin.

Example:

wrappers:
  - exclusion:
      resources:
        myresource1
builders:
  - critical-block-start
  - ... other builders
  - critical-block-end
critical-block-start

Designate the start of a critical block. Must be used in conjuction with critical-block-end.

Must also add a build wrapper (exclusion), specifying the resources that control the critical block. Otherwise, this will have no effect.

Requires Jenkins Exclusion Plugin.

Example:

wrappers:
  - exclusion:
      resources:
        myresource1
builders:
  - critical-block-start
  - ... other builders
  - critical-block-end
gradle

Execute gradle tasks. Requires the Jenkins Gradle Plugin.

Parameters:
  • tasks (str) – List of tasks to execute
  • gradle-name (str) – Use a custom gradle name (optional)
  • wrapper (bool) – use gradle wrapper (default false)
  • executable (bool) – make gradlew executable (default false)
  • switches (list) – Switches for gradle, can have multiples
  • use-root-dir (bool) – Whether to run the gradle script from the top level directory or from a different location (default false)
  • root-build-script-dir (str) – If your workspace has the top-level build.gradle in somewhere other than the module root directory, specify the path (relative to the module root) here, such as ${workspace}/parent/ instead of just ${workspace}.

Example:

builders:
  - gradle:
      gradle-name: "gradle-1.2"
      wrapper: true
      executable: true
      use-root-dir: true
      root-build-script-dir: ${workspace}/tests
      switches:
        - "-g /foo/bar/.gradle"
        - "-PmavenUserName=foobar"
      tasks: |
             init
             build
             tests
grails

Execute a grails build step. Requires the Jenkins Grails Plugin.

Parameters:
  • use-wrapper (bool) – Use a grails wrapper (default false)
  • name (str) – Select a grails installation to use (optional)
  • force-upgrade (bool) – Run ‘grails upgrade –non-interactive’ first (default false)
  • non-interactive (bool) – append –non-interactive to all build targets (default false)
  • targets (str) – Specify target(s) to run separated by spaces
  • server-port (str) – Specify a value for the server.port system property (optional)
  • work-dir (str) – Specify a value for the grails.work.dir system property (optional)
  • project-dir (str) – Specify a value for the grails.project.work.dir system property (optional)
  • base-dir (str) – Specify a path to the root of the Grails project (optional)
  • properties (str) – Additional system properties to set (optional)
  • plain-output (bool) – append –plain-output to all build targets (default false)
  • stack-trace (bool) – append –stack-trace to all build targets (default false)
  • verbose (bool) – append –verbose to all build targets (default false)
  • refresh-dependencies (bool) – append –refresh-dependencies to all build targets (default false)

Example:

builders:
  - grails:
      use-wrapper: "true"
      name: "grails-2.2.2"
      force-upgrade: "true"
      non-interactive: "true"
      targets: "war ear"
      server-port: "8003"
      work-dir: "./grails-work"
      project-dir: "./project-work"
      base-dir: "./grails/project"
      properties: "program.name=foo"
      plain-output: "true"
      stack-trace: "true"
      verbose: "true"
      refresh-dependencies: "true"
groovy

Execute a groovy script or command. Requires the Jenkins Groovy Plugin

Parameters:
  • file (str) – Groovy file to run. (Alternative: you can chose a command instead)
  • command (str) – Groovy command to run. (Alternative: you can chose a script file instead)
  • version (str) – Groovy version to use. (default ‘(Default)’)
  • parameters (str) – Parameters for the Groovy executable. (optional)
  • script-parameters (str) – These parameters will be passed to the script. (optional)
  • properties (str) – Instead of passing properties using the -D parameter you can define them here. (optional)
  • java-opts (str) – Direct access to JAVA_OPTS. Properties allows only -D properties, while sometimes also other properties like -XX need to be setup. It can be done here. This line is appended at the end of JAVA_OPTS string. (optional)
  • class-path (str) – Specify script classpath here. Each line is one class path item. (optional)

Examples:

builders:
  - groovy:
      file: "test.groovy"
builders:
  - groovy:
      command: "Some command"
      version: "Groovy 1.2"
      parameters: "parameters"
      script-parameters: "script parameters"
      properties: "properties"
      java-opts: "java opts"
inject

Inject an environment for the job. Requires the Jenkins EnvInject Plugin.

Parameters:
  • properties-file (str) – the name of the property file (optional)
  • properties-content (str) – the properties content (optional)

Example:

builders:
  - inject:
      properties-file: example.prop
      properties-content: EXAMPLE=foo-bar
managed-script

This step allows to reference and execute a centrally managed script within your build. Requires the Jenkins Managed Script Plugin.

Parameters:
  • script-id (str) – Id of script to execute (Required)
  • type (str) –

    Type of managed file (default: script)

    type values:
    • batch: Execute managed windows batch
    • script: Execute managed script
  • args (list) – Arguments to be passed to referenced script

Example:

builders:
  - managed-script:
      script-id: org.jenkinsci.plugins.managedscripts.ScriptConfig1401886156431
      type: script
      args:
        - arg1
        - arg2
builders:
  - managed-script:
      script-id: org.jenkinsci.plugins.managedscripts.WinBatchConfig1402391729132
      type: batch
      args:
        - arg1
        - arg2
maven-target

Execute top-level Maven targets

Parameters:
  • goals (str) – Goals to execute
  • properties (str) – Properties for maven, can have multiples
  • pom (str) – Location of pom.xml (default ‘pom.xml’)
  • private-repository (bool) – Use private maven repository for this job (default false)
  • maven-version (str) – Installation of maven which should be used (optional)
  • java-opts (str) – java options for maven, can have multiples, must be in quotes (optional)
  • settings (str) – Path to use as user settings.xml (optional)
  • global-settings (str) – Path to use as global settings.xml (optional)

Example:

builders:
        - maven-target:
            maven-version: Maven3
            pom: parent/pom.xml
            goals: clean
            private-repository: true
            properties:
              - foo=bar
              - bar=foo
            java-opts:
              - "-Xms512m -Xmx1024m"
              - "-XX:PermSize=128m -XX:MaxPermSize=256m"
            settings: mvn/settings.xml              
            global-settings: mvn/globalsettings.xml
msbuild

Build .NET project using msbuild. Requires the Jenkins MSBuild Plugin.

Parameters:
  • msbuild-version (str) – which msbuild configured in Jenkins to use (optional)
  • solution-file (str) – location of the solution file to build
  • extra-parameters (str) – extra parameters to pass to msbuild (optional)
  • pass-build-variables (bool) – should build variables be passed to msbuild (default true)
  • continue-on-build-failure (bool) – should the build continue if msbuild returns an error (default false)

Example:

builders:
  - msbuild:
      solution-file: "MySolution.sln"
      msbuild-version: "msbuild-4.0"
      extra-parameters: "/maxcpucount:4"
      pass-build-variables: False
      continue-on-build-failure: True
multijob

Define a multijob phase. Requires the Jenkins Multijob Plugin.

This builder may only be used in jenkins_jobs.modules.project_multijob.MultiJob projects.

Parameters:
  • name (str) – MultiJob phase name
  • condition (str) – when to trigger the other job (default ‘SUCCESSFUL’)
  • projects (list) –

    list of projects to include in the MultiJob phase

    Project:
    • name (str) – Project name
    • current-parameters (bool) – Pass current build parameters to the other job (default false)
    • node-label-name (str) – Define a list of nodes on which the job should be allowed to be executed on. Requires NodeLabel Parameter Plugin (optional)
    • node-label (str) – Define a label of ‘Restrict where this project can be run’ on the fly. Requires NodeLabel Parameter Plugin (optional)
    • git-revision (bool) – Pass current git-revision to the other job (default false)
    • property-file (str) – Pass properties from file to the other job (optional)
    • predefined-parameters (str) – Pass predefined parameters to the other job (optional)
    • kill-phase-on (str) – Stop the phase execution on specific job status. Can be ‘FAILURE’, ‘UNSTABLE’, ‘NEVER’. (optional)

Example:

builders:
  - multijob:
      name: PhaseOne
      condition: SUCCESSFUL
      projects:
        - name: PhaseOneJobA
          current-parameters: true
          node-label-name: "vm_name"
          node-label: "agent-${BUILD_NUMBER}"
          git-revision: true
        - name: PhaseOneJobB
          current-parameters: true
          property-file: build.props
  - multijob:
      name: PhaseTwo
      condition: UNSTABLE
      projects:
        - name: PhaseTwoJobA
          current-parameters: true
          predefined-parameters: foo=bar
        - name: PhaseTwoJobB
          current-parameters: false
          kill-phase-on: UNSTABLE
powershell

Execute a powershell command. Requires the Powershell Plugin.

Parameter:the powershell command to execute

Example:

builders:
  - powershell: "foo/foo.ps1"
python

Execute a python command. Requires the Jenkins Python plugin.

Parameters:parameter (str) – the python command to execute

Example:

builders:
  - python: 'import foobar'
sbt

Execute a sbt build step. Requires the Jenkins Sbt Plugin.

Parameters:
  • name (str) – Select a sbt installation to use. If no name is provided, the first in the list of defined SBT builders will be used. (default to first in list)
  • jvm-flags (str) – Parameters to pass to the JVM (default ‘’)
  • actions (str) – Select the sbt tasks to execute (default ‘’)
  • sbt-flags (str) – Add flags to SBT launcher (default ‘-Dsbt.log.noformat=true’)
  • subdir-path (str) – Path relative to workspace to run sbt in (default ‘’)

Example:

builders:
  - sbt:
      name: "default"
      actions: "clean package"
      jvm-flags: "-Xmx8G"
shell

Execute a shell command.

Parameters:parameter (str) – the shell command to execute

Example:

builders:
  - shell: "make test"
shining-panda

Execute a command inside various python environments. Requires the Jenkins ShiningPanda plugin.

Parameters:build-environment (str) –

Building environment to set up (Required).

build-environment values:
 
  • python: Use a python installation configured in Jenkins.
  • custom: Use a manually installed python.
  • virtualenv: Create a virtualenv

For the python environment

Parameters:python-version (str) – Name of the python installation to use. Must match one of the configured installations on server configuration (default: System-CPython-2.7)

For the custom environment:

Parameters:home (str) – path to the home folder of the custom installation (Required)

For the virtualenv environment:

Parameters:
  • python-version (str) – Name of the python installation to use. Must match one of the configured installations on server configuration (default: System-CPython-2.7)
  • name (str) – Name of this virtualenv. Two virtualenv builders with the same name will use the same virtualenv installation (optional)
  • clear (bool) – If true, delete and recreate virtualenv on each build. (default: false)
  • use-distribute (bool) – if true use distribute, if false use setuptools. (default: true)
  • system-site-packages (bool) – if true, give access to the global site-packages directory to the virtualenv. (default: false)

Common to all environments:

Parameters:
  • nature (str) –

    Nature of the command field. (default: shell)

    nature values:
    • shell: execute the Command contents with default shell
    • xshell: like shell but performs platform conversion first
    • python: execute the Command contents with the Python executable
  • command (str) – The command to execute
  • ignore-exit-code (bool) – mark the build as failure if any of the commands exits with a non-zero exit code. (default: false)

Examples:

builders:
    - shining-panda:
        build-environment: python
        python-version: System-CPython-2.7
        nature: python
        command: setup.py build
        ignore-exit-code: false
builders:
    - shining-panda:
        build-environment: custom
        home: /usr/local/lib/custom-python-27
        nature: xshell
        command: |
            cd $HOME/build
            python setup.py build
        ignore-exit-code: true
builders:
    - shining-panda:
        build-environment: virtualenv
        python-version: System-CPython-2.7
        nature: shell
        command: python setup.py build
        name: virtvenv1
        clear: true
        use-distribute: true
        system-site-packages: true
        ignore-exit-code: true
ssh

Send files or execute commands over SSH. Requires the Jenkins Publish over SSH Plugin.

Parameters:
  • site (str) – name of the ssh site
  • target (str) – destination directory
  • target-is-date-format (bool) – whether target is a date format. If true, raw text should be quoted (defaults to False)
  • clean-remote (bool) – should the remote directory be deleted before transferring files (defaults to False)
  • source (str) – source path specifier
  • command (str) – a command to execute on the remote server (optional)
  • timeout (int) – timeout in milliseconds for the Exec command (optional)
  • use-pty (bool) – run the exec command in pseudo TTY (defaults to False)
  • excludes (str) – excluded file pattern (optional)
  • remove-prefix (str) – prefix to remove from uploaded file paths (optional)
  • fail-on-error (bool) – fail the build if an error occurs (defaults to False).

Example:

builders:
  - ssh:
      site: 'server.example.com'
      target: 'dest/dir'
      source: 'base/source/dir/**'
      remove-prefix: 'base/source/dir'
      excludes: '**/*.excludedfiletype'
      use-pty: true
      command: 'rm -r jenkins_$BUILD_NUMBER'
      timeout: 1800000
system-groovy

Execute a system groovy script or command. Requires the Jenkins Groovy Plugin

Parameters:
  • file (str) – Groovy file to run. (Alternative: you can chose a command instead)
  • command (str) – Groovy command to run. (Alternative: you can chose a script file instead)
  • bindings (str) – Define variable bindings (in the properties file format). Specified variables can be addressed from the script. (optional)
  • class-path (str) – Specify script classpath here. Each line is one class path item. (optional)

Examples:

builders:
  - system-groovy:
      file: "test.groovy"
builders:
  - system-groovy:
      command: "Some command"
      bindings: "Some bindings"
      class-path: "Some classpath"
trigger-builds

Trigger builds of other jobs. Requires the Jenkins Parameterized Trigger Plugin.

Parameters:
  • project (str) – the Jenkins project to trigger
  • predefined-parameters (str) – key/value pairs to be passed to the job (optional)
  • property-file (str) – Pass properties from file to the other job (optional)
  • property-file-fail-on-missing (bool) – Don’t trigger if any files are missing (optional) (default true)
  • current-parameters (bool) – Whether to include the parameters passed to the current build to the triggered job.
  • svn-revision (bool) – Whether to pass the svn revision to the triggered job
  • block (bool) – whether to wait for the triggered jobs to finish or not (default false)
  • same-node (bool) – Use the same node for the triggered builds that was used for this build (optional)
  • parameter-factories (list) –

    list of parameter factories

    Factory:
    • factory (str) filebuild – For every property file, invoke one build
    • file-pattern (str) – File wildcard pattern
    • no-files-found-action (str) – Action to perform when no files found (optional) [‘FAIL’, ‘SKIP’, ‘NOPARMS’] (default ‘SKIP’)
    Factory:
    • factory (str) binaryfile – For every matching file, invoke one build
    • file-pattern (str) – Artifact ID of the artifact
    • no-files-found-action (str) – Action to perform when no files found (optional) [‘FAIL’, ‘SKIP’, ‘NOPARMS’] (default ‘SKIP’)
    Factory:
    • factory (str) counterbuild – Invoke i=0...N builds
    • from (int) – Artifact ID of the artifact
    • to (int) – Version of the artifact
    • step (int) – Classifier of the artifact
    • parameters (str) – KEY=value pairs, one per line (default ‘’)
    • validation-fail (str) – Action to perform when stepping validation fails (optional) [‘FAIL’, ‘SKIP’, ‘NOPARMS’] (default ‘FAIL’)

Examples:

Basic usage.

builders:
  - trigger-builds:
    - project: "build_started"
      predefined-parameters:
        FOO="bar"
      current-parameters: true
      svn-revision: true
      block: true

Example with all supported parameter factories.

builders:
  - trigger-builds:
    - project: "build_started"
      predefined-parameters:
        FOO="bar"
      current-parameters: true
      svn-revision: true
      parameter-factories:
        - factory: filebuild
          file-pattern: propfile*.txt
        - factory: binaryfile
          parameter-name: filename
          file-pattern: otherpropfile*.txt
        - factory: counterbuild
          from: 0
          to: 5
          step: 1
      block: true

Previous topic

Matrix Project

Next topic

Hipchat

This Page