Build variables

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

Note

Some features and predefined variables are not available in certain versions of TFS. We're working on updating this topic to call out these differences.

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

Use User-defined Predefined, all scopes Predefined, agent scope Format Examples and more information
As arguments to build tasks Yes Yes Yes $(Build.DefinitionName) Command line, Copy files
Apply a version control label during the build process Yes Yes No $(Build.DefinitionName) Repository tab (Git and Team Foundation version control Label format)
Customize the build number Yes Yes No $(Build.DefinitionName) Build number format options
Environment variable in Windows batch scripts Yes Yes Yes %BUILD_DEFINITIONNAME% Batch script
Environment variable in PowerShell scripts Yes Yes Yes $env:BUILD_DEFINITIONNAME PowerShell script
Environment variable in Shell scripts Yes Yes Yes $BUILD_DEFINITIONNAME Shell script

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 Secret if it contains a password, keys, or some other kind of data that you need to avoid exposing.

TFS 2017.2, TFS 2017.3

Keep password secret

TFS 2017 RTM

Keep password secret

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 tasks are not given access by default.

  • Decrypted for access by your build tasks. So you can use them in password arguments and also pass them explicitly into a script or a program from your build task (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. Note that the updated variable value is scoped to the phase being executed and does not flow across phases.

Tip

You can run a script on a:

Batch script

icon Set the sauce and secretSauce variables

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

icon Read the variables

Arguments

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

Script

@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)

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

Build.Clean

Modifies how the build agent cleans things up. See Source repositories.

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 tasks. For example, on the Build tab of a build definition, add this task:

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

Note

If you have defined the a variable of the same name (for example PATH) on the variables tab, then your value overrides the environment variable when you use it as shown above.

Predefined variables

Agent.BuildDirectory

Environment variable: AGENT_BUILDDIRECTORY

Scope: Agent

The local path on the agent where all folders for a given build definition are created.

For example: c:\agent\_work\1

For example:

  • In TFS 2015.4: C:\TfsData\Agents\Agent-MACHINENAME\_work\1

  • In TFS 2015 RTM: C:\TfsData\Build\_work\6c3842c6

Agent.HomeDirectory

Environment variable: AGENT_HOMEDIRECTORY

Scope: Agent

The directory the agent is installed into. This contains the agent software.

For example: c:\agent

For example:

  • In TFS 2015.4: C:\TfsData\Agents\Agent-MACHINENAME

  • In TFS 2015 RTM:

    • Pre-configured agent: C:\Program Files\Microsoft Team Foundation Server 14.0\Build

    • Agent installed by you: C:\Agent

This directory is specified by you. See Agents.

Agent.Id

Environment variable: AGENT_ID

Scope: Agent

The ID of the agent.

Agent.JobStatus

Environment variable: AGENT_JOBSTATUS or agent.jobstatus

Environment variable: agent.jobstatus

Scope: Agent

The status of the build.

  • Canceled
  • Failed
  • Succeeded
  • SucceededWithIssues (partially successful)

Agent.MachineName

Environment variable: AGENT_MACHINENAME

Scope: Agent

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

Note

This variable is available in TFS 2015.4, not in TFS 2015 RTM.

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

Environment variable: BUILD_ARTIFACTSTAGINGDIRECTORY

Scope: Agent

The local path on the agent where any artifacts are copied to before being pushed to their destination. For example:

  • TFS 2015.4: C:\TfsData\Agents\Agent-MACHINENAME\_work\1\a

  • TFS 2015 RTM default agent: C:\TfsData\Build_work\6c3842c6\artifacts

  • TFS 2015 RTM agent installed by you: C:\Agent_work\6c3842c6\artifacts

This directory is purged before each new build, so you don't have to clean it up yourself.

A typical way to use this folder is to publish your build artifacts with the Copy files and Publish build artifacts tasks. See Artifacts in Team Build.

In TFS 2015.4, Build.ArtifactStagingDirectory and Build.StagingDirectory are interchangeable.

The local path on the agent where any artifacts are copied to before being pushed to their destination. For example: c:\agent\_work\1\a

A typical way to use this folder is to publish your build artifacts with the Copy files and Publish build artifacts tasks.

Note

Build.ArtifactStagingDirectory and Build.StagingDirectory are interchangeable. This directory is purged before each new build, so you don't have to clean it up yourself.

See Artifacts in Team Build.

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

Build.BinariesDirectory (TFS 2015.4)

Environment variable: BUILD_BINARIESDIRECTORY

Scope: Agent

The local path on the agent you can use as an output folder for compiled binaries.

For example: c:\agent\_work\1\b.

For example: C:\TfsData\Agents\Agent-MACHINENAME\_work\1\b

By default, new build definitions are not set up to clean this directory. You can define your build to clean it up on the Repository tab.

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.

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.

Build.StagingDirectory

Environment variable: BUILD_STAGINGDIRECTORY

Scope: Agent

TFS 2015 RTM

The local path on the agent you can use as an output folder for compiled binaries. For example: C:\TfsData\Build\_work\6c3842c6\staging.

By default, new build definitions are not set up to clean this directory. You can define your build to clean it up on the Repository tab.

TFS 2015.4

The local path on the agent where any artifacts are copied to before being pushed to their destination. For example: C:\TfsData\Agents\Agent-MACHINENAME\_work\1\a

This directory is purged before each new build, so you don't have to clean it up yourself.

A typical way to use this folder is to publish your build artifacts with the Copy files and Publish build artifacts tasks. See Artifacts in Team Build.

In TFS 2015.4, Build.ArtifactStagingDirectory and Build.StagingDirectory are interchangeable.

The local path on the agent where any artifacts are copied to before being pushed to their destination. For example: c:\agent\_work\1\a

A typical way to use this folder is to publish your build artifacts with the Copy files and Publish build artifacts tasks.

Note

Build.ArtifactStagingDirectory and Build.StagingDirectory are interchangeable. This directory is purged before each new build, so you don't have to clean it up yourself.

See Artifacts in Team Build.

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

Build.TriggeredBy.BuildId

Environment variable: BUILD_TRIGGEREDBY_BUILDID

Scope: Agent

If the build was triggered by another build, then this variable is set to the BuildID of the triggering build.

Build.TriggeredBy.DefinitionId

Environment variable: BUILD_TRIGGEREDBY_DEFINITIONID

If the build was triggered by another build, then this variable is set to the DefinitionID of the triggering build.

Build.TriggeredBy.BuildDefinitionName

Environment variable: BUILD_TRIGGEREDBY_DEFINITIONNAME

If the build was triggered by another build, then this variable is set to the name of the triggering build definition.

Build.TriggeredBy.BuildNumber

Environment variable: BUILD_TRIGGEREDBY_BUILDNUMBER

If the build was triggered by another build, then this variable is set to the number of the triggering build.

Build.TriggeredBy.ProjectID

Environment variable: BUILD_TRIGGEREDBY_PROJECTID

If the build was triggered by another build, then this variable is set to ID of the team project that contains the triggering build.

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

Environment variable: SYSTEM_HOSTTYPE

Scope: All

Set to build if the process is a build or release if the process is a release.

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

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.

If the build is triggered... Then the Build.QueuedBy and Build.QueuedById values are based on... Then the Build.RequestedFor and Build.RequestedForId values are based on...
In Git or TFVC by the Continuous integration (CI) triggers The system identity, for example: [DefaultCollection]\Project Collection Service Accounts The person who pushed or checked in the changes.
In Git or by a branch policy build. The system identity, for example: [DefaultCollection]\Project Collection Service Accounts The person who checked in the changes.
In TFVC by a gated check-in trigger The person who checked in the changes. The person who checked in the changes.
In Git or TFVC by the Scheduled triggers The system identity, for example: [DefaultCollection]\Project Collection Service Accounts The system identity, for example: [DefaultCollection]\Project Collection Service Accounts
Because you clicked the Queue build button You You

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.

I use TFS on-premises and I don't see some of these features. Why not?

Some of these features are available only on VSTS and not yet available on-premises. Some features are available on-premises if you have upgraded to the latest version of TFS.