| ms.topic | ms.service | ms.manager | ms.author | author | ms.date |
|---|---|---|---|---|---|
include |
azure-devops-pipelines |
mijacobs |
jukullam |
juliakm |
06/29/2023 |
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.
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're using a self-hosted agent, then this name get set by you. See agents. |
| Agent.OS | The operating system of the agent host. Valid values are:
|
| Agent.OSArchitecture | The operating system processor architecture of the agent host. Valid values are:
|
| Agent.TempDirectory | A temporary folder that is cleaned after each pipeline job. This directory is used by tasks such as .NET Core CLI task to hold temporary items like test results before they're 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 add tools from this directory to PATH so that subsequent build steps can use them. Learn about managing this directory on a self-hosted agent. |
| Agent.WorkFolder | The working directory for this agent. For example: c:\agent_work. This directory isn't guaranteed to be writable by pipeline tasks (for example, when mapped into a container). |
| Variable | Description |
|---|---|
| Build.ArtifactStagingDirectory | 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 Azure Pipelines. 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 fails. 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.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. By default, new build pipelines aren't set up to clean this directory. You can define your build to clean it up on the Repository tab. For example: c:\agent_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 fails. |
| Build.QueuedById | See "How are the identity variables set?". |
| Build.Reason | The event that caused the build to run.
|
| 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\sBy 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.
|
| 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: 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 fails. |
| Build.RequestedForEmail | See "How are the identity variables set?". |
| Build.RequestedForId | See "How are the identity variables set?". |
| Build.SourceBranch | The branch the build was queued for. Some examples:
/) are replaced with underscore characters (_). Note: In TFVC, if you're running a gated check-in build or manually building a shelveset, you can't use this variable in your build number format. |
| Build.SourceBranchName | The name of the branch the build was queued for.
|
| 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.SourceVersion | The latest version control change that is included in this build. 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. 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. Note: This variable is available in TFS 2015.4. Note: The Build.SourceVersionMessage variable does not work with classic build pipelines in Bitbucket repositories when Batch changes while a build is in progress is enabled. |
| Build.StagingDirectory | 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 Azure Pipelines. 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're running a gated build or a shelveset build, this is set to the name of the shelveset you're building. Note: This variable yields a value that is invalid for build use in a build number format. |
| Build.TriggeredBy.BuildId | If the build was triggered by another build, then this variable is set to the BuildID of the triggering build. 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.TriggeredBy.DefinitionId | If the build was triggered by another build, then this variable is set to the DefinitionID of the triggering build. 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.TriggeredBy.DefinitionName | If the build was triggered by another build, then this variable is set to the name of the triggering build pipeline. 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.TriggeredBy.BuildNumber | If the build was triggered by another build, then this variable is set to the number of the triggering build. 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.TriggeredBy.ProjectID | If the build was triggered by another build, then this variable is set to ID of the project that contains the triggering build. 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. |
| 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. 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. |
Example PowerShell script: access REST API
| Variable | Description |
|---|---|
| System.AccessToken | Use the OAuth token to access the REST API. Use System.AccessToken from YAML scripts. 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 | [!INCLUDE include] |
| 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.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. |
| 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.PullRequestNumber | 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.SourceCommitId | The commit that is being reviewed in a pull request. (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 isn't initialized for GitHub PRs.) |
| System.PullRequest.TargetBranch | The branch that is the target of a pull request. For example: refs/heads/main. 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. |