Variable Expansion

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

Important

Pipeline:

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:

jenkins-${NODE_NAME}-${JOB_NAME}-${EXECUTOR_NUMBER}
  • 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.
  • Note

    The EXECUTOR_NUMBER variable is not required if concurrent builds are disabled because they might cause the job to create multiple workspaces when you only want one workspace created.

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}/...
Tip

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}/...
Note

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.