Build variables

• 04/19/2018
• 14 minutes to read

VSTS | TFS 2018 | TFS 2017 | TFS 2015 | Previous versions (XAML builds)

Variables give you a convenient way to get key bits of data into various parts of your build process.

User-defined variables

Variables are a great way to store and share key bits of data in your build definition. Some build templates automatically define some variables for you.

For example, when you create a new .NET app build, BuildConfiguration and BuildPlatform are automatically defined for you.

User-defined variables are formatted differently in different contexts. See above table.

Secret Variables

We recommend that you make the variable Secret if it contains a password, keys, or some other kind of data that you need to avoid exposing.

Secret variables are:

• Encrypted at rest with a 2048-bit RSA key.

• Not returned back to the client. They are automatically masked out of any log output from the build or release.

• Not decrypted into environment variables. So scripts and programs run by your build steps are not given access by default.

• Decrypted for access by your build steps. So you can use them in password arguments and also pass them explicitly into a script or a program from your build step (for example as $(password)).

Allow at queue time

Select this check box if you want to enable your team to modify the value when they manually queue a build.

Define and modify your variables in a script

To define or modify a variable from a script, use the task.setvariable logging command.

@echo ##vso[task.setvariable variable=sauce]crushed tomatoes
@echo ##vso[task.setvariable variable=secretSauce;issecret=true]crushed tomatoes with garlic

"$(sauce)" "$(secretSauce)"

@echo off
set sauceArgument=%~1
set secretSauceArgument=%~2
@echo No problem reading %sauceArgument% or %SAUCE%
@echo But I cannot read %SECRETSAUCE%
@echo But I can read %secretSauceArgument% (but the log is redacted so I do not spoil
     the secret)

Write-Host "##vso[task.setvariable variable=sauce]crushed tomatoes"
Write-Host "##vso[task.setvariable variable=secretSauce;issecret=true]crushed tomatoes with
            garlic"

-sauceArgument "$(sauce)" -secretSauceArgument "$(secretSauce)"

Param(
   [string]$sauceArgument,
   [string]$secretSauceArgument
)
Write-Host No problem reading $env:sauce or $sauceArgument
Write-Host But I cannot read $env:secretSauce
Write-Host But I can read $secretSauceArgument "(but the log is redacted so I do not
           spoil the secret)"

#!/bin/bash
echo "##vso[task.setvariable variable=sauce]crushed tomatoes"
echo "##vso[task.setvariable variable=secretSauce;issecret=true]crushed tomatoes with garlic"

"$(sauce)" "$(secretSauce)"

#!/bin/bash
echo "No problem reading $1 or $SAUCE"
echo "But I cannot read $SECRETSAUCE"
echo "But I can read $2 (but the log is redacted so I do not spoil the secret)"

Console output from reading the variables:

No problem reading crushed tomatoes or crushed tomatoes
But I cannot read 
But I can read ******** (but the log is redacted so I do not spoil the secret)

Control variables

System.Debug

If you need more detailed logs to debug build problems, define and set it to true.

Environment variables

You can pass environment variables of the build machine into build steps. For example, on the Build tab of a build definition, add this step:

Task	Arguments
Utility: Command Line	Tool: echo Arguments: $(PATH)

Predefined variables

Agent.MachineName

Environment variable: AGENT_MACHINENAME

Scope: Agent

The name of the machine on which the agent is installed.

Agent.Name

Environment variable: AGENT_NAME

Scope: Agent

The name of the agent that is registered with the pool.

If you are using an on-premises agent, this directory is specified by you. See agents(../concepts/agents/agents.md).

Agent.WorkFolder

Environment variable: AGENT_WORKFOLDER

Scope: Agent

The working directory for this agent. For example: c:\agent\_work.

Build.BuildId

Environment variable: BUILD_BUILDID

Scope: All

The ID of the record for the completed build.

Build.BuildNumber

Environment variable: BUILD_BUILDNUMBER

Scope: Agent, label format (see Notes)

The name of the completed build. You can specify the build number format that generates this value in the definition options.

A typical use of this variable is to make it part of the label format, which you specify on the repository tab.

Note: This value can contain whitespace or other invalid label characters. In these cases, the label format will fail.

Build.BuildUri

Environment variable: BUILD_BUILDURI

Scope: Agent

The URI for the build. For example: vstfs:///Build/Build/1430.

Build.DefinitionName

Environment variable: BUILD_DEFINITIONNAME

Scope: All (see Notes)

The name of the build definition.

Note: This value can contain whitespace or other invalid label characters. In these cases, the label format will fail.

Build.DefinitionVersion

Environment variable: BUILD_DEFINITIONVERSION

Scope: All

The version of the build definition.

Build.QueuedBy

Environment variable: BUILD_QUEUEDBY

Scope: All (see Notes)

How are the identity variables set?

Note: This value can contain whitespace or other invalid label characters. In these cases, the label format will fail.

Build.QueuedById

Environment variable: BUILD_QUEUEDBYID

Scope: All

How are the identity variables set?

Build.Reason

Environment variable: BUILD_REASON

Scope: All

VSTS Only

The event that caused the build to run.

• Manual: A user manually queued the build.
• IndividualCI: Continuous integration (CI) triggered by a Git push or a TFVC check-in.
• BatchedCI: Continuous integration (CI) triggered by a Git push or a TFVC check-in, and the Batch changes was selected.
• Schedule: Scheduled trigger.
• ValidateShelveset: A user manually queued the build of a specific TFVC shelveset.
• CheckInShelveset: Gated check-in trigger.
• PullRequest: The build was triggered by a Git branch policy that requires a build. ::: moniker range="vsts"
• BuildCompletion: The build was triggered by another build ::: moniker-end

See Build definition triggers, Improve code quality with branch policies.

Build.Repository.Clean

Environment variable: BUILD_REPOSITORY_CLEAN

Scope: Agent

The value you've selected for Clean in the source repository settings.

Build.Repository.LocalPath

Environment variable: BUILD_REPOSITORY_LOCALPATH

Scope: Agent

The local path on the agent where your source code files are downloaded. For example: c:\agent\_work\1\s

By default, new build definitions update only the changed files. You can modify how files are downloaded on the Repository tab.

Build.Repository.Name

Environment variable: BUILD_REPOSITORY_NAME

Scope: Agent

The name of the repository.

Build.Repository.Provider

Environment variable: BUILD_REPOSITORY_PROVIDER

Scope: Agent

The type of repository you selected.

• TfsGit: TFS Git repository
• TfsVersionControl: Team Foundation Version Control
• Git: Git repository hosted on an external server
• GitHub
• Svn: Subversion

Build.Repository.Tfvc.Workspace

Environment variable: BUILD_REPOSITORY_TFVC_WORKSPACE

Scope: Agent

Defined if your repository is Team Foundation Version Control. The name of the TFVC workspace used by the build agent.

For example, if the Agent.BuildDirectory is c:\agent\_work\12 and the Agent.Id is 8, the workspace name could be: ws_12_8

Build.Repository.Uri

Environment variable: BUILD_REPOSITORY_URI

Scope: Agent

The URL for the repository. For example:

• Git: https://fabrikamfiber.visualstudio.com/_git/Scripts
• TFVC: https://fabrikamfiber.visualstudio.com/

Build.RequestedFor

Environment variable: BUILD_REQUESTEDFOR

Scope: All (see Notes)

How are the identity variables set?

Note: This value can contain whitespace or other invalid label characters. In these cases, the label format will fail.

Build.RequestedForEmail

Environment variable: BUILD_REQUESTEDFOREMAIL

Scope: All

How are the identity variables set?

Build.RequestedForId

Environment variable: BUILD_REQUESTEDFORID

Scope: All

How are the identity variables set?

Build.SourceBranch

Environment variable: BUILD_SOURCEBRANCH

Scope: All (see Notes)

The branch the build was queued for. Some examples:

• Git repo branch: refs/heads/master
• Git repo pull request: refs/pull/1/merge
• TFVC repo branch: $/teamproject/main
• TFVC repo gated check-in: Gated_2016-06-06_05.20.51.4369;username@live.com
• TFVC repo shelveset build: myshelveset;username@live.com

When you use this variable in your build number format, the forward slash characters (/) are replaced with underscore characters _).

Note: In TFVC, if you are running a gated check-in build or manually building a shelveset, you cannot use this variable in your build number format.

Build.SourceBranchName

Environment variable: BUILD_SOURCEBRANCHNAME

Scope: All (see Notes)

The name of the branch the build was queued for.

• Git repo branch or pull request: The last path segment in the ref. For example, in refs/heads/master this value is master.
• TFVC repo branch: The last path segment in the root server path for the workspace. For example in $/teamproject/main this value is main.
• TFVC repo gated check-in or shelveset build is the name of the shelveset. For example, Gated_2016-06-06_05.20.51.4369;username@live.com or myshelveset;username@live.com.

Note: In TFVC, if you are running a gated check-in build or manually building a shelveset, you cannot use this variable in your build number format.

Build.SourcesDirectory

Environment variable: BUILD_SOURCESDIRECTORY

Scope: Agent

The local path on the agent where your source code files are downloaded. For example: c:\agent\_work\1\s

By default, new build definitions update only the changed files. You can modify how files are downloaded on the Repository tab.

Build.SourceVersion

Environment variable: BUILD_SOURCEVERSION

Scope: Agent

The latest version control change that is included in this build.

• Git: The commit ID.
• TFVC: the changeset.

Build.Repository.Git.SubmoduleCheckout

Environment variable: BUILD_REPOSITORY_GIT_SUBMODULECHECKOUT

Scope: Agent

The value you've selected for Checkout submodules on the repository tab.

Build.SourceTfvcShelveset

Environment variable: BUILD_SOURCETFVCSHELVESET

Scope: All (see Notes)

Defined if your repository is Team Foundation Version Control.

If you are running a gated build or a shelveset build, this is set to the name of the shelveset you are building.

Note: This variable yields a value that is invalid for build use in a build number format

Common.TestResultsDirectory

Environment variable: COMMON_TESTRESULTSDIRECTORY

Scope: Agent

The local path on the agent where the test results are created. For example: c:\agent\_work\1\TestResults

System.AccessToken

Environment variable: SYSTEM_ACCESSTOKEN

Scope: Agent

Use the OAuth token to access the REST API.

System.CollectionId

Environment variable: SYSTEM_COLLECTIONID

Scope: All

The GUID of the team foundation collection.

System.DefaultWorkingDirectory

Environment variable: SYSTEM_DEFAULTWORKINGDIRECTORY

Scope: Agent

The local path on the agent where your source code files are downloaded. For example: c:\agent\_work\1\s

By default, new build definitions update only the changed files. You can modify how files are downloaded on the Repository tab.

System.DefinitionId

Environment variable: SYSTEM_DEFINITIONID

Scope: All

The ID of the build definition.

System.PullRequest.IsFork

Environment variable: SYSTEM_PULLREQUEST_ISFORK

Scope: All

If the pull request is from a fork of the repository, this variable is set to True. Otherwise, it is set to False.

System.PullRequest.PullRequestId

Environment variable: SYSTEM_PULLREQUEST_PULLREQUESTID

Scope: All

The ID of the pull request that caused this build. For example: 17. (This variable is initialized only if the build ran because of a Git PR affected by a branch policy.)

System.PullRequest.PullRequestNumber

Environment variable: SYSTEM_PULLREQUEST_PULLREQUESTNUMBER

Scope: All

The number of the pull request that caused this build. This variable is populated for pull requests from GitHub which have a different pull request ID and pull request number.

System.PullRequest.SourceBranch

Environment variable: SYSTEM_PULLREQUEST_SOURCEBRANCH

Scope: All

The branch that is being reviewed in a pull request. For example: refs/heads/users/raisa/new-feature. (This variable is initialized only if the build ran because of a Git PR affected by a branch policy.)

System.PullRequest.SourceRepositoryURI

Environment variable: SYSTEM_PULLREQUEST_SOURCEREPOSITORYURI

Scope: All

VSTS Only

The URL to the repo that contains the pull request. For example: https://ouraccount.visualstudio.com/_git/OurProject. (This variable is initialized only if the build ran because of a VSTS Git PR affected by a branch policy. It is not initialized for GitHub PRs.)

System.PullRequest.TargetBranch

Environment variable: SYSTEM_PULLREQUEST_TARGETBRANCH

Scope: All

The branch that is the target of a pull request. For example: refs/heads/master. (This variable is initialized only if the build ran because of a Git PR affected by a branch policy.)

System.TeamFoundationCollectionUri

Environment variable: SYSTEM_TEAMFOUNDATIONCOLLECTIONURI

Scope: Agent

The URI of the team foundation collection. For example: https://fabrikamfiber.visualstudio.com/.

System.TeamProject

Environment variable: SYSTEM_TEAMPROJECT

Scope: All

The name of the team project that contains this build.

System.TeamProjectId

Environment variable: SYSTEM_TEAMPROJECTID

Scope: All

The ID of the team project that this build belongs to.

TF_BUILD

Scope: Agent

Set to True if the script is being run by a build step.

Q&A

What are the predefined Release Management variables?

Default release management variables

How are the identity variables set?

The value depends on what caused the build.

Do I need an agent?

You need at least one agent to run your build or release. Get an agent.

I can't select a default agent queue and I can't queue my build or release. How do I fix this?

See Agent pools and queues.