Predefined variables

In this article

In Microsoft Team Foundation Server (TFS) 2018 and previous versions,
run 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 the comprehensive list of predefined variables.

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.

Note

You can use release variables in your deploy tasks to share the common information (e.g. — Environment Name, Resource Group, etc)

Build.Clean

This is a deprecated variable that modifies how the build agent cleans up source.
To learn how to clean up source, see source repositories.

This variable modifies how the build agent cleans up source.
To learn more, see source repositories.

System.AccessToken

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

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 is a script that could use $SYSTEM_ACCESSTOKEN
env:
SYSTEM_ACCESSTOKEN: $(System.AccessToken)
- powershell: Write-Host "This is a script that could use $env:SYSTEM_ACCESSTOKEN"
env:
SYSTEM_ACCESSTOKEN: $(System.AccessToken)

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

Navigate to the job

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.

Agent variables

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: c:\agent_work\1

Agent.HomeDirectory

The directory the agent is installed into. This contains the agent software. For example: c:\agent.

Agent.Id

The ID of the agent.

Agent.JobName

The name of the running job. This will usually be "Job" or "__default", but in multi-config scenarios, will be the configuration.

Agent.JobStatus

The status of the build.

Canceled

Failed

Succeeded

SucceededWithIssues (partially successful)

The environment variable should be referenced as AGENT_JOBSTATUS. The older agent.jobstatus is available for backwards compatibility.

Agent.MachineName

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

Agent.Name

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

If you are using a self-hosted agent, then this name is specified by you. See agents.

Agent.OS

The operating system of the agent host. Valid values are:

Windows_NT

Darwin

Linux

If you're running in a container, the agent host and container may be running different operating systems.

Agent.OSArchitecture

The operating system processor architecture of the agent host. Valid values are:

X86

X64

ARM

Agent.TempDirectory

A temporary folder that is cleaned after each pipeline run. This directory is used by tasks such as .NET Core CLI task to hold temporary items like test results before they are published.

Agent.ToolsDirectory

The directory used by tasks such as Node Tool Installer and Use Python Version to switch between multiple versions of a tool.
These tasks will add tools from this directory to PATH so that subsequent build steps can use them.

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.

Common.TestResultsDirectory

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

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.

Pipeline variables

Variable

Description

Pipeline.Workspace

Workspace directory for a particular pipeline.

For example, c:\agent_work\1.

Deployment job variables

These variables are scoped to a specific Deployment job and will be resolved only at job execution time.

Variable

Description

Environment.Name

Name of the environment targeted in the deployment job to run the deployment steps and record the deployment history. For example, smarthotel-dev.

Environment.Id

ID of the environment targeted in the deployment job. For example, 10.

Environment.ResourceName

Name of the specific resource within the environment targeted in the deployment job to run the deployment steps and record the deployment history. For example, bookings which is a Kubernetes namespace that has been added as a resource to the environment smarthotel-dev.

Environment.ResourceId

ID of the specific resource within the environment targeted in the deployment job to run the deployment steps. For example, 4.

System variables

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.

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. For a release, the values are deployment for a Deployment group job and release for an Agent job.

System.JobAttempt

Set to 1 the first time this job is attempted, and increments every time the job is retried.

System.JobDisplayName

The human-readable name given to a job.

System.JobName

The name of the job, typically used for expressing dependencies and accessing output variables.

System.PhaseAttempt

Set to 1 the first time this phase is attempted, and increments every time the job is retried.

Note: "Phase" is a mostly-redundant concept which represents the design-time for a job (whereas job was the runtime version of a phase). We've mostly removed the concept of "phase" from Azure Pipelines. Matrix and multi-config jobs are the only place where "phase" is still distinct from "job". One phase can instantiate multiple jobs which differ only in their inputs.

System.PhaseDisplayName

The human-readable name given to a phase.

System.PhaseName

A string-based identifier for a job, typically used for expressing dependencies and accessing output variables.

System.StageAttempt

Set to 1 the first time this stage is attempted, and increments every time the job is retried.

System.StageDisplayName

The human-readable name given to a stage.

System.StageName

A string-based identifier for a stage, typically used for expressing dependencies and accessing output variables.

System.PullRequest.IsFork

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

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

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: https://dev.azure.com/ouraccount/_git/OurProject. (This variable is initialized only if the build ran because of a Azure Repos Git PR affected by a branch policy. It is not initialized for GitHub PRs.)

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: https://dev.azure.com/fabrikamfiber/.

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.

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

Agent variables

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: c:\agent_work\1

Agent.HomeDirectory

The directory the agent is installed into. This contains the agent software. For example: c:\agent.

Agent.Id

The ID of the agent.

Agent.JobName

The name of the running job. This will usually be "Job" or "__default", but in multi-config scenarios, will be the configuration.

Agent.JobStatus

The status of the build.

Canceled

Failed

Succeeded

SucceededWithIssues (partially successful)

The environment variable should be referenced as AGENT_JOBSTATUS. The older agent.jobstatus is available for backwards compatibility.

Agent.MachineName

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

Agent.Name

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

If you are using a self-hosted agent, then this name is specified by you. See agents.

Agent.OS

The operating system of the agent host. Valid values are:

Windows_NT

Darwin

Linux

If you're running in a container, the agent host and container may be running different operating systems.

Agent.OSArchitecture

The operating system processor architecture of the agent host. Valid values are:

X86

X64

ARM

Agent.TempDirectory

A temporary folder that is cleaned after each pipeline run. This directory is used by tasks such as .NET Core CLI task to hold temporary items like test results before they are published.

Agent.ToolsDirectory

The directory used by tasks such as Node Tool Installer and Use Python Version to switch between multiple versions of a tool.
These tasks will add tools from this directory to PATH so that subsequent build steps can use them.

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

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: https://dev.azure.com/ouraccount/_git/OurProject. (This variable is initialized only if the build ran because of a Azure Repos Git PR affected by a branch policy. It is not initialized for GitHub PRs.)

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: https://dev.azure.com/fabrikamfiber/.

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.

Agent variables

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: c:\agent_work\1

Agent.HomeDirectory

The directory the agent is installed into. This contains the agent software. For example: c:\agent.

Agent.Id

The ID of the agent.

Agent.JobStatus

The status of the build.

Canceled

Failed

Succeeded

SucceededWithIssues (partially successful)

The environment variable should be referenced as AGENT_JOBSTATUS. The older agent.jobstatus is available for backwards compatibility.

A temporary folder that is cleaned after each pipeline run. This directory is used by tasks such as .NET Core CLI task to hold temporary items like test results before they are published.

Agent.ToolsDirectory

The directory used by tasks such as Node Tool Installer and Use Python Version to switch between multiple versions of a tool.
These tasks will add tools from this directory to PATH so that subsequent build steps can use them.

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.

Agent variables

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: c:\agent_work\1

Agent.ComputerName

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

Agent.HomeDirectory

The directory the agent is installed into. This contains the agent software. For example: c:\agent.

Agent.Id

The ID of the agent.

Agent.JobStatus

The status of the build.

Canceled

Failed

Succeeded

SucceededWithIssues (partially successful)

The environment variable should be referenced as AGENT_JOBSTATUS. The older agent.jobstatus is available for backwards compatibility.

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.

Agent variables

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.

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.

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