This is the documentation for Bamboo 5.8. View this page for the

Unknown macro: {spacejump}

of Bamboo, or visit the latest Bamboo documentation.

Variables can be used to make values available when building plans in Bamboo.

  • Build-specific variables are evaluated by Bamboo dynamically at build time. The source of a build-specific variable can either be a Bamboo property or one of the default plugins (assuming it is enabled).
  • Deployment variables are available when deploying a project. 
  • System variables also apply across your entire Bamboo instance and inherit their values from system or environment variables of the same name.
  • Global variables are defined across your entire Bamboo instance, and have the same (static) value for every plan that is built by Bamboo. See Defining global variables.
  • Plan variables are similar to global variables, but are defined for specific plans. Plan variables override global variables with the same name. You can also override a plan variable for a build if you trigger the build manually. See Defining plan variables.

Using variables

Variables can be used in all fields of a task or deployment, with the exception of password fields. Use the following format when referencing a variable:

${bamboo.variableName}

You can override a plan variable for a build, if you trigger the build manually. See Triggering a plan build manually.

(warning) You cannot reference a variable from another variable in Bamboo, i.e. "double de-referencing". See this knowledge base article for more information.

Defining custom variables

You can define your own custom variables, using a similar format to that above, however you cannot create a variable name that is already in use by Bamboo.

For information on how to define your own variables in Bamboo, see:

Build-specific variables

The following build-specific variables are available by default:

Build-specific variable

Description

bamboo.buildKey

The job key for the current job, in the form PROJECT-PLAN-JOB, e.g. BAM-MAIN-JOBX

bamboo.planKeyThe key of the current plan, in the form PROJECT-PLAN, e.g. BAM-MAIN
bamboo.shortPlanKeyThe short key of the current plan (without project part), e.g. MAIN
bamboo.shortJobKeyThe short key of the current job (without project and plan parts), e.g. JOBX

bamboo.buildResultKey

The result key when this job executes, in the form PROJECT-PLAN-JOB-BUILD e.g. BAM-BOO-JOB1-8, where '8' is the build number. For deployment projects this variable will not have the JOB component e.g. PROJ-TP-6.

bamboo.buildResultsUrl

or

bamboo.resultsUrl

The URL of the result in Bamboo once the job has finished executing.

bamboo.buildNumber

The Bamboo build number, e.g. 123

bamboo.buildPlanName

The Bamboo job name e.g. Some Project name - Some plan name - Some job name

bamboo.planNameThe current plan's name e.g. Some project name - Some plan name
bamboo.shortPlanNameThe current plan's name without project part, e.g. Some plan name
bamboo.shortJobNameThe current job's name without project and plan parts, e.g. Some job name

bamboo.buildTimeStamp

The time when build was started in ISO 8601 format e.g. 2010-01-01T01:00:00.000+01:00

bamboo.agentIdThe ID of the agent that the deployment is executed on.
bamboo.agentWorkingDirectoryThe path to the working directory on the agent. This is not the same as the Bamboo working directory.

bamboo.working.directory

The working directory that the build is being executed on.

bamboo.ManualBuildTriggerReason.userNameThe user who triggered the manual build.
Generic repository variables 
bamboo.planRepository.<position>.branchNameThe name of the branch in the repository (depends on availability from the VCS used) e.g. default
bamboo.planRepository.<position>.nameThe name of of the repository, as shown in the repository for the plan e.g. Mercurial
bamboo.planRepository.<position>.revisionThe revision use to build this release. Format depends on the VCS used.
bamboo.planRepository.<position>.previousrevisionThe previous revision number (this might not exist, for example for the initial build).
bamboo.planRepository.<position>.typeThe type of the repository, as defined by a repository plugin e.g. hg, svn, git
Subversion 

bamboo.planRepository.<position>.revision.number

The revision number.

bamboo.planRepository.<position>.lastchange.revision.number

The last-changed revision number.

bamboo.planRepository.<position>.username

User name, used for repository authentication.

bamboo.planRepository.<position>.repositoryUrl

The repository URL.

CVS 

bamboo.planRepository.<position>.last.update.time

The last updated timestamp.

bamboo.planRepository.<position>.last.update.time.label

The last updated timestamp to be used as a label for post build result labelling. The spaces in the cvs version string are replaced with '_'.

Perforce 

bamboo.planRepository.<position>.revision.number

The change set number.

bamboo.planRepository.<position>.username

User name, used for repository authentication.

bamboo.planRepository.<position>.port

Port used for repository communication.

bamboo.planRepository.<position>.client

Client used for repository communication.

Git 
bamboo.planRepository.<position>.branchThe branch
bamboo.planRepository.<position>.repositoryUrlThe repository URL
Mercurial 

bamboo.planRepository.<position>.repositoryUrl

The repository URL

bamboo.planRepository.<position>.branch

The branch

bamboo.planRepository.<position>.username

User name, used for repository authentication.

  • System variables also apply across your entire Bamboo instance and inherit their values from system or environment variables of the same name.
  • In the variable names from the table above, <position> is an optional parameter that specifies the position of the repository in the plan's repository list. If omitted, the first repository in the list is used.
  • Third-party repository plugins can expose their own variables.

Build dependency variables

The following build dependency variables are also available:

Build-specific variable

Description

bamboo.dependency.parent.#

Allows a child build to query the build key of the triggering parent build, where # represents the position in the build tree - 0 at the top, 1 the following, and so on. The ${bamboo.dependency.parent.0} variable can be viewed in the child plan's metadata tab.

dependency.parent.totalThe total # of parent builds.

Deployment variables

Bamboo manages a number of standard reserved variables that are available when deploying a project. 

Variables later in the following list override the previous ones in case of repeating names:

  • global variables
  • release variables as defined below
  • user variables defined at environment level
  • the autogenerated variables in the following table:
VariableDescription
bamboo.agentIdThe id of the agent that the deployment is executed on.
bamboo.agentWorkingDirectoryThe path to the working directory on the agent. This is not the same as the Bamboo working directory.
bamboo.build.working.directoryThe path to the working directory for Bamboo. This is used by both the build plan and the deployment project.
bamboo.deploy.environmentThe name of the environment that the release is to be deployed to.
bamboo.deploy.projectThe name of the deployment project.
bamboo.deploy.rollbackTrue if the release being deployed is older than the release being replaced.

bamboo.deploy.release

bamboo.deploy.version

The name of the release that is being deployed. Either .release or .version can be used - both return the name of the release being deployed.

bamboo.deploy.release.previous

bamboo.deploy.version.previous

The name of the release that is being replaced (if available). Either .release or .version can be used - both return the name of the release being replaced.
bamboo.resultsUrlThe URL to the screen in Bamboo that dispays build results.

You can generate variables of your own, using a similar format, however you cannot create a variable that is already in use by Bamboo. See Defining deployment environment variables for more information.

Releases variables

Bamboo makes the following types of variables available for deployment releases:

  • Snapshots of values for global variables.
  • Snapshots of values for plan variables.
  • Snapshots of values of repository variables.
  • The autogenerated release variables in the following table:
VariableDescription
bamboo.buildNumberThe build result from which the release is created.
bamboo.buildResultKeyThe key of the build result from which the release is created e.g. KUNG-FOO-JOB1-35
bamboo.planKeyThe key of the plan related to the release e.g. KUNG-FOO
bamboo.planNameThe name of the plan related to the release e.g. Kung - Foo
bamboo.shortPlanKeyThe short key of the plan related to the release (without project part), e.g. MAIN
bamboo.shortPlanNameThe plan's name without project part, e.g. Some plan name

Note that several of the variables in the above table are actually those associated with the build plan.

System variables

The usage format for all system variables is:

${system.<variable>}

For example, if you have a system variable MYPATH=C:\MyPath; you can use a Bamboo system variable system.MYPATH which will inherit the same value as the system variable.

(info) In older Bamboo versions using 'PATH' in the Environment Variables field (of a Script task) doesn't set the windows PATH variable, whereas using 'Path' sets Path and PATH in cmd shell.

Using variables in bash

Bamboo variables are exported as bash shell variables. All full stops (periods) are converted to underscores. For example, the variable bamboo.my.variable is $bamboo_my_variable in bash. This is related to File Script tasks (not Inline Script tasks).

JIRA applications variables

Note that these variables can be accessed from a Bamboo build only when that build was triggered by releasing a version in a JIRA application.

JIRA variableDescription
${bamboo.jira.baseUrl}The URL of your JIRA application server.
${bamboo.jira.projectKey}The key of the triggering the JIRA application project.
${bamboo.jira.projectName}The name of the triggering JIRA application project.
${bamboo.jira.version}The release version of the triggering JIRA application project.
${bamboo.jira.username}The username of the user who triggered the release build.

Examples

Maven examples

For example, you may want your Maven 2 version to be determined by Bamboo. In Maven 2 pom.xml you may have:

...
<groupId>com.atlassian.boo</groupId>
<artifactId>boo-test</artifactId>
<packaging>jar</packaging>
<version>1.1.${bambooBuildNumber}-SNAPSHOT</version>
...

You can then specify the following in the Goal field of your build plan:

clean package -DbambooBuildNumber=${bamboo.buildNumber}

When the command runs, Bamboo will replace the buildNumber with the actual number (e.g. 1102), which will be passed to the underlying Maven build to use. The command will then produce a jar that looks like this: boo-test-1.1.1102-SNAPSHOT.jar.

Ant examples

You can then specify the following in the Target field of your build plan:

-f build.xml -DbambooBuildNumber=${bamboo.buildNumber}

When the command runs, Bamboo will replace the buildNumber with the actual number (e.g. 1102), which will be passed to the underlying Ant build to use.

Specifying capabilities as variables

You can also specify a capability to be used in a similar way to a global variable.

The format of the capability should be as follows:

${bamboo.capability.<capability_key>}

For example,

  • Custom

    ${bamboo.capability.<capability_key>}
  • JDK

    ${bamboo.capability.system.jdk.<jdk_label>}
  • Builder

    ${bamboo.capability.system.builder.<builder_type>.<builder_label>}
    e.g. ${bamboo.capability.system.builder.maven.Maven1}
  • Perforce

    ${bamboo.capability.system.p4Executable}

If you click on a capability, the specific capability key will be contained in the URL.

Please note, the space characters in the URL will be replaced with '+' characters. We recommend that you do not use capability labels with space characters, if you wish to use them as variables. A possible solution for space characters is to format them with '${}' symbols, however, this does not work in all cases.

Using capabilities

Global and Build-Specific Variables can be used in a specific fields of your build plan, as specified above. For capabilities,

  • System Capabilities are available to all of these fields, (i.e. global and build-specific).
  • Agent Capabilities (i.e. agent-specific and shared/server capabilities) are available only to the build-specific fields. (i.e. not available to Repository URLCVS Root or Branch name.)

For example,

If you wanted to specify a system variable, but have it set to different values on each agent, do the following:

  • Set the following as a system environment variable field on the Builder tab:

    ${bamboo.capability.thatsystemvariable}
  • Specify the system environment variable as a custom capability on each of your agents, and set to the capability to the different values, as desired.

Deprecated variables

The following variables are deprecated and are subject for removal in future Bamboo releases:

Generic repository variables 

bamboo.repository.revision.number

The revision number.

bamboo.repository.branch.nameThe repository branch name (for Bamboo version 4.2 or later).

bamboo.repository.previous.revision.number

The previous revision number (might not exist, for example for the initial build).

Subversion 

bamboo.custom.svn.revision.number

The revision number.

bamboo.custom.svn.lastchange.revision.number

The last changed revision number.

bamboo.custom.svn.username

User name used for repository authentication.

bamboo.repository.svn.repositoryUrl

The repository URL.

CVS 

bamboo.custom.cvs.last.update.time

The last updated timestamp.

bamboo.custom.cvs.last.update.time.label

The last updated timestamp to be used as a label for post build result labelling. The spaces in the CVS version string are replaced with '_'.

Perforce 

bamboo.custom.p4.revision.number

The change set number.

bamboo.custom.p4.username

User name used for repository authentication.

bamboo.custom.p4.port

Port used for repository communication.

bamboo.custom.p4.client

Client used for repository communication.

Git 
bamboo.repository.git.branchThe branch.
bamboo.repository.git.repositoryUrlThe repository URL.
Mercurial 

bamboo.repository.hg.repositoryUrl

The repository URL.

bamboo.repository.hg.branch

The branch.

bamboo.repository.hg.username

User name, used for repository authentication.