Bamboo variables

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.
  • Project variables are defined for specific projects. Project variables can override global variables with the same name. See Defining project variables.
  • Plan variables are similar to global variables, but are defined for specific plans. Plan variables override global and project 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.

You can reference a variable from another variables, e.g. consider having the following variables:

  • var1 = Hello
  • var2 = world
                    

You can create another variable which references the two other one.

greet
${bamboo.var1} ${bamboo.var2}! 

Bamboo will resolve the variable as Hello World!

You can:

  • reference a global or context specific variable in a build plan or deployment project
  • reference a variable which references another one, deep recursion is allowed

There are couple of limitations:

  • referencing a variable which isn't defined is an error, whole build or deployment will fail if you reference such variable
  • cycles are not allowed and are considered as build or deployment project error.

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:

  • System variables 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, <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-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.shortPlanBranchNameThe name of the current plan branch where the job is being run
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 a job was started in ISO 8601 format (for example, 2010-01-01T01:00:00.000+01:00)
bamboo.agentIdThe ID of the agent that the deployment is executed on.
bamboo.agentWorkingDirectory

The path to the working directory on the agent, for example <HOME>/xml-data/build-dir.

The agent working directory is not the same as the build working directory described below.

bamboo.build.working.directory

The working directory on which the build is being executed, for example <HOME>/xml-data/build-dir/AV-AVT-JOB1.


bamboo.ManualBuildTriggerReason.userNameThe user who triggered the manual build.
bamboo.triggerReason.keyThe trigger key that caused the build to launch; for example: com.atlassian.bamboo.plugin.system.triggerReason:ManualBuildTriggerReason
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
bamboo.repository.pr.keyPull request key if plan branch was created from pull request
bamboo.repository.pr.sourceBranchPull request source branch name if plan branch was created from pull request
bamboo.repository.pr.targetBranchPull request destination branch name if plan branch was created from pull request
bamboo.planRepository.branchDisplayNameThe name of the branch displayed in the branch details section.
Subversion

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 labeling. 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.

bamboo.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
  • project variables of the plan linked to the deployment project
  • plan variables of the plan linked to the deployment project
  • release variables as defined below
  • user variables defined at the 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 displays build results.
bamboo.triggerReason.key

The trigger key that caused the deployment to launch. For example:

com.atlassian.bamboo.plugin
.
system.triggerReason
:ManualBuildTriggerReason

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:

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-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. The snapshots mentioned above do not contain password variables.

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 and 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 Jira Software.

Jira variableDescription
${bamboo.jira.baseUrl}The URL of your Jira application server.
${bamboo.jira.projectKey}The key of the triggering 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 select 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 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. If many repositories are linked to the plan, the variable stores the revision number of the last repository in the list.

bamboo.repository.branch.nameThe repository branch name (for Bamboo version 4.2 or later). If many repositories are linked to the plan, the variable stores the branch name of the first repository in the list.

bamboo.repository.previous.revision.number

The previous revision number (might not exist, for example for the initial build). If many repositories are linked to the plan, the variable stores the previous revision number of the first repository in the list.

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.

bamboo.planRepository.<position>.revision.number

The revision number.

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

The last-changed revision number.

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 labeling. 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.

Last modified on Jan 18, 2024

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.