Variable Expansion

Many of the workspace fields can include environment variables to help define their value.



When using variables in a script they must be surrounded by single quotes as shown in the following examples:

  • name: 'jenkins-${NODE_NAME}-${JOB_NAME}-${EXECUTOR_NUMBER}',
  • format: 'jenkins-${NODE_NAME}-${JOB_NAME}-${EXECUTOR_NUMBER}',
  • description: 'Updated by Jenkins. Build: ${BUILD_URL}',
  • review: '${P4_REVIEW}',
  • view: '//depot/projects/alpha/... //${P4_CLIENT}/...'
  • If you have multiple View Mappings, the variables are surrounded by three single quotes:
  • view: '''//depot/projects/alpha/... //${P4_CLIENT}/... //depot/projects/beta/... //${P4_CLIENT}/...'''

Using full double quotes " expands the variables early and the script will fail.

Workspace name

For example: we recommend that the Workspace name uses at least the following variables to help identify your builds:

  • NODE_NAME - Name of the "slave" or "master" the job is built on, such as linux.
  • JOB_NAME - Name of the project of this build, such as "foo"
  • EXECUTOR_NUMBER - The unique number that identifies the current executor. If the job is called 'foo' and it is built on a slave called 'linux' the variables expand the name to: jenkins-linux-foo

Multiple Syncs

If you need more than one sync task in a script you MUST use a different workspace name.

You can control this by customizing the Workspace Name Format field. The default value is jenkins-${NODE_NAME}-${JOB_NAME}-${EXECUTOR_NUMBER} and will not appear in the generated snippet, however if you change this to jenkins-${NODE_NAME}-${JOB_NAME}-${EXECUTOR_NUMBER}-libs you will see a new attribute in the snippet format: 'jenkins-${NODE_NAME}-${JOB_NAME}-${EXECUTOR_NUMBER}-libs'.

Built in environment variables

Jenkins provides a set of environment variables. You can also define your own. Here is a list of built in environment variables:

  • BUILD_NUMBER - The current build number. For example "153"
  • BUILD_ID - The current build id. For example "2018-08-22_23-59-59"
  • BUILD_DISPLAY_NAME - The name of the current build. For example "#153".
  • JOB_NAME - Name of the project of this build. For example "foo"
  • BUILD_TAG - String of "jenkins-${JOB_NAME}-${BUILD_NUMBER}".
  • EXECUTOR_NUMBER - The unique number that identifies the current executor.
  • NODE_NAME - Name of the "slave" or "master". For example "linux".
  • NODE_LABELS - Whitespace-separated list of labels that the node is assigned.
  • WORKSPACE - Absolute path of the build as a workspace.
  • JENKINS_HOME - Absolute path on the master node for Jenkins to store data.
  • JENKINS_URL - URL of Jenkins. For example http://server:port/jenkins/
  • BUILD_URL - Full URL of this build. For example http://server:port/jenkins/job/foo/15/
  • JOB_URL - Full URL of this job. For example http://server:port/jenkins/job/foo/

Perforce environment variables

Helix Plugin for Jenkins provides a set of Perforce environment variables.

  • P4_CHANGELIST - The last Perforce changelist number included in the populated workspace.
  • P4_CLIENT - The Perforce client workspace name. Equivalent to jenkins-${NODE_NAME}-${JOB_NAME}-${EXECUTOR_NUMBER}.
  • P4_PORT - The Perforce Helix server connection port. For example "perforce:1666".
  • P4_ROOT - The Perforce client workspace root path.
  • P4_USER - The Perforce username.
  • P4_TICKET - A valid Perforce ticket (if the credential is valid).
  • P4_REVIEW - The Swarm Review ID.
  • P4_REVIEW_TYPE - The Swarm Review Type ('shelved' or 'committed').
  • HUDSON_CHANGELOG_FILE - Location of the changelog file.

Variables in workspace view and stream paths

The plugin allows the use of environment variables in fields like Workspace view and Stream path.

For example:

//depot/main/proj/... //jenkins-${NODE_NAME}-${JOB_NAME}-${EXECUTOR_NUMBER}/...

To get the same result as the example above with less typing, replace the variables in the example with the Perforce variable //${P4_CLIENT}/....

//depot/main/proj/... //{$P4_CLIENT}/...

Define your own variables

With a Matrix build you might have defined your own variables like ${OS}. Remember they can be used anywhere in the mapping:

//depot/main/${JOB_NAME}/bin.${OS}/... //jenkins-${NODE_NAME}-${JOB_NAME}-${EXECUTOR_NUMBER}-${OS}/bin/${OS}/...

In client views, depot paths, and stream paths: If you create a variable and it is not defined during a build, the variable key is used as the value in the mapping.

For example, if you use the ${OS} variable in a mapping and its value is not defined, OS is used as the value in the mapping.