Use predefined variables

TFS 2017 | TFS 2015

Note

In Microsoft Team Foundation Server (TFS) 2018 and previous versions, build and release pipelines are called definitions, runs are called builds, service connections are called service endpoints, stages are called environments, and jobs are called phases.

Variables give you a convenient way to get key bits of data into various parts of your pipeline. This is a list of predefined variables that are available for your use. There may be a few other predefined variables, but they are mostly for internal use.

These variables are automatically set by the system and read-only. (The exceptions are Build.Clean and System.Debug.)

Learn more about working with variables.

Build.Clean

This variable modifies how the build agent cleans up source. To learn more, see Clean the local repo on the agent.

System.AccessToken

System.AccessToken is a special variable that carries the security token used by the running build.

YAML

In YAML, you must explicitly map System.AccessToken into the pipeline using a variable. You can do this at the step or task level:

steps:
  - bash: echo This script could use $SYSTEM_ACCESSTOKEN
    env:
      SYSTEM_ACCESSTOKEN: $(System.AccessToken)
  - powershell: | 
      Write-Host "This is a script that could use $env:SYSTEM_ACCESSTOKEN"
      Write-Host "$env:SYSTEM_ACCESSTOKEN = $(System.AccessToken)"
    env:
      SYSTEM_ACCESSTOKEN: $(System.AccessToken)

You can configure the default scope for System.AccessToken using build job authorization scope.

Classic

You can allow scripts and tasks to access System.AccessToken at the job level.

1. Navigate to the job

2. Under Additional options, check the Allow scripts to access the OAuth token box.

Checking this box also leaves the credential set in Git so that you can run pushes and pulls in your scripts.

System.Debug

For more detailed logs to debug pipeline problems, define System.Debug and set it to true.

1. Edit your pipeline.

2. Select Variables.

3. Add a new variable with the name System.Debug and value true.

   

4. Save the new variable.

Agent variables (TFS 2015)

Note

You can use agent variables as environment variables in your scripts and as parameters in your build tasks. You cannot use them to customize the build number or to apply a version control label or tag.

Variable	Description
Agent.BuildDirectory	The local path on the agent where all folders for a given build pipeline are created. For example: TFS 2015.4: C:\TfsData\Agents\Agent-MACHINENAME_work\1 TFS 2015 RTM user-installed agent: C:\Agent_work\6c3842c6 TFS 2015 RTM built-in agent: C:\TfsData\Build_work\6c3842c6
Agent.HomeDirectory	The directory the agent is installed into. This contains the agent software. For example: TFS 2015.4: C:\TfsData\Agents\Agent-MACHINENAME TFS 2015 RTM user-installed agent: C:\Agent TFS 2015 RTM built-in agent: C:\Program Files\Microsoft Team Foundation Server 14.0\Build
Agent.Id	The ID of the agent.
Agent.JobStatus	The status of the build. Canceled Failed Succeeded SucceededWithIssues (partially successful) Note: The environment variable can be referenced only as agent.jobstatus. AGENT_JOBSTATUS was not present in TFS 2015.
Agent.MachineName	The name of the machine on which the agent is installed. This variable is available in TFS 2015.4, not in TFS 2015 RTM.
Agent.Name	The name of the agent that is registered with the pool. This name is specified by you. See agents.
Agent.WorkFolder	The working directory for this agent. For example: c:\agent_work.

Build variables (TFS 2015)

Variable	Description
Build.ArtifactStagingDirectory	The local path on the agent where any artifacts are copied to before being pushed to their destination. 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 Azure Pipelines. 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. In TFS 2015.4, Build.ArtifactStagingDirectory and Build.StagingDirectory are interchangeable. This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
Build.BuildId	The ID of the record for the completed build.
Build.BuildNumber	The name of the completed build. You can specify the build number format that generates this value in the pipeline 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. This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of a version control tag.
Build.BuildUri	The URI for the build. For example: vstfs:///Build/Build/1430. This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
Build.BinariesDirectory	The local path on the agent you can use as an output folder for compiled binaries. Available in TFS 2015.4. By default, new build pipelines are not set up to clean this directory. You can define your build to clean it up on the Repository tab. For example: C:\TfsData\Agents\Agent-MACHINENAME_work\1\b This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
Build.DefinitionName	The name of the build pipeline. Note: This value can contain whitespace or other invalid label characters. In these cases, the label format will fail.
Build.DefinitionVersion	The version of the build pipeline.
Build.QueuedBy	See "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	See "How are the identity variables set?".
Build.Repository.Clean	The value you've selected for Clean in the source repository settings. This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
Build.Repository.LocalPath	The local path on the agent where your source code files are downloaded. For example: c:\agent_work\1\s By default, new build pipelines update only the changed files. You can modify how files are downloaded on the Repository tab. This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. This variable is synonymous with Build.SourcesDirectory.
Build.Repository.Name	The name of the repository. This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
Build.Repository.Provider	The type of repository you selected. TfsGit: TFS Git repository TfsVersionControl: Team Foundation Version Control Git: Git repository hosted on an external server Svn: Subversion (available on TFS 2015.4) This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
Build.Repository.Tfvc.Workspace	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 This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
Build.Repository.Uri	The URL for the repository. For example: Git: https://fabrikamfiber/tfs/DefaultCollection/Scripts/_git/Scripts TFVC: https://fabrikamfiber/tfs/DefaultCollection/ This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
Build.RequestedFor	See "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.RequestedForId	See "How are the identity variables set?".
Build.SourceBranch	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	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. In refs/heads/feature/tools this value is tools. 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	The local path on the agent where your source code files are downloaded. For example: c:\agent_work\1\s By default, new build pipelines update only the changed files. You can modify how files are downloaded on the Repository tab. This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. This variable is synonymous with Build.Repository.LocalPath.
Build.SourcesDirectoryHash	Note: This variable is available in TFS 2015 RTM, but not in TFS 2015.4.
Build.SourceVersion	The latest version control change that is included in this build. Git: The commit ID. TFVC: the changeset. This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
Build.SourceVersionMessage	The comment of the commit or changeset. We truncate the message to the first line or 200 characters, whichever is shorter. This variable is agent-scoped, and can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag. Note: This variable is available in TFS 2015.4.
Build.StagingDirectory	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 pipelines 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 Azure Pipelines. In TFS 2015.4, Build.ArtifactStagingDirectory and Build.StagingDirectory are interchangeable. All versions of TFS 2015 This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
Build.Repository.Git.SubmoduleCheckout	The value you've selected for Checkout submodules on the repository tab. This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
Build.SourceTfvcShelveset	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	The local path on the agent where the test results are created. For example: c:\agent_work\1\TestResults. Available in TFS 2015.4. This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.

System variables (TFS 2015)

Variable	Description
System.AccessToken	Available in TFS 2015.4. Use the OAuth token to access the REST API. This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
System.CollectionId	The GUID of the TFS collection or Azure DevOps organization
System.DefaultWorkingDirectory	The local path on the agent where your source code files are downloaded. For example: c:\agent_work\1\s By default, new build pipelines update only the changed files. You can modify how files are downloaded on the Repository tab. This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
System.DefinitionId	The ID of the build pipeline.
System.HostType	Set to build if the pipeline is a build or release if the pipeline is a release.
System.PullRequest.PullRequestId	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.SourceBranch	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	The URL to the repo that contains the pull request. For example: http://our-server:8080/tfs/DefaultCollection/_git/OurProject. (This variable is initialized only if the build ran because of a Azure Repos Git PR affected by a branch policy.)
System.PullRequest.TargetBranch	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	The URI of the team foundation collection. For example: http://our-server:8080/tfs/DefaultCollection/. This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.
System.TeamProject	The name of the project that contains this build.
System.TeamProjectId	The ID of the project that this build belongs to.
TF_BUILD	Set to True if the script is being run by a build task. This variable is agent-scoped. It can be used as an environment variable in a script and as a parameter in a build task, but not as part of the build number or as a version control tag.

How are the identity variables set?

The value depends on what caused the build and are specific to Azure Repos repositories.

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