Release variables
As you compose the tasks for deploying your application into each environment, variables will help you to:
- Define a more generic deployment process once, and then customize it easily for each environment. For example, a variable can be used to represent the connection string for web deployment, and the value of this variable can be changed from one environment to another. These are custom variables.
- Use information about the context of the particular release, environment, artifacts, or agent in which the deployment process is being run. For example, your script may need access to the location of the build to download it, or to the working directory on the agent to create temporary files. These are default variables.
You can view the current values of all variables for a release, and use a default variable to run a release in debug mode.
Custom variables
Custom variables can be defined at various scopes.
-
Share values across all of the definitions in a project by using variable groups. Choose a variable group when you need to use the same values across all the definitions, environments, and tasks in a project, and you want to be able to change the values in a single place. You define and manage variable groups in the Library tab.
-
Share values across all of the environments by using release definition variables. Choose a release definition variable when you need to use the same value across all the environments and tasks in the release definition, and you want to be able to change the value in a single place. You define and manage these variables in the Variables tab in a release definition.
-
Share values across all of the tasks within one specific environment by using environment variables. Use an environment-level variable for values that vary from environment to environment (and are the same for all the tasks in an environment). You define and manage these variables in the Variables tab of an environment in a release definition.
Using custom variables at project, release definition, and environment scope helps you to:
-
Avoid duplication of values, making it easier to update all occurrences as one operation.
-
Store sensitive values in a way that they cannot be seen or changed by users of the release definitions. Designate a configuration property to be a secure (secret) variable by selecting the
(padlock) icon next to the variable.The values of hidden (secret) variables are stored securely on the server and cannot be viewed by users after they are saved. During a deployment, the Release Management service decrypts these values when referenced by the tasks and passes them to the agent over a secure HTTPS channel.
Default variables
Information about the execution context is made available to running tasks through default variables. Your tasks and scripts can use these variables to find information about the system, release, environment, or agent they are running in. With the exception of System.Debug, these variables are read-only and their values are automatically set by the system. Some of the most significant variables are described in the following tables.
System variables
| Variable name | Description | Example | Not available in |
|---|---|---|---|
| System.TeamFoundationServerUri | The URL of the Release Management service endpoint in the TFS or VSTS account. Use this from your scripts or tasks to call REST APIs on the Release Management service. | https://fabrikam.vsrm.visualstudio.com/ | |
| System.TeamFoundationCollectionUri | The URL of the Team Foundation collection or VSTS account. Use this from your scripts or tasks to call REST APIs on other services such as Build and Version control. | https://fabrikam.visualstudio.com/ | |
| System.CollectionId | The ID of the collection to which this build or release belongs. | 6c6f3423-1c84-4625-995a-f7f143a1e43d | TFS 2015 |
| System.TeamProject | The name of the project to which this build or release belongs. | Fabrikam | |
| System.TeamProjectId | The ID of the project to which this build or release belongs. | 79f5c12e-3337-4151-be41-a268d2c73344 | TFS 2015 |
| System.ArtifactsDirectory | The directory to which artifacts are downloaded during deployment of a release. The directory is cleared before every deployment if it requires artifacts to be downloaded to the agent. Same as Agent.ReleaseDirectory and System.DefaultWorkingDirectory. | C:\agent_work\r1\a | |
| System.DefaultWorkingDirectory | The directory to which artifacts are downloaded during deployment of a release. The directory is cleared before every deployment if it requires artifacts to be downloaded to the agent. Same as Agent.ReleaseDirectory and System.ArtifactsDirectory. | C:\agent_work\r1\a | |
| System.WorkFolder | The working directory for this agent, where subfolders are created for every build or release. Same as Agent.RootDirectory and Agent.WorkFolder. | C:\agent_work | |
| System.Debug | This is the only system variable that can be set by the users. Set this to true to run the release in debug mode to assist in fault-finding. | true |
Release variables
| Variable name | Description | Example | Not available in |
|---|---|---|---|
| Release.DefinitionName | The name of the release definition to which the current release belongs. | fabrikam-cd | |
| Release.DefinitionId | The ID of the release definition to which the current release belongs. | 1 | TFS 2015 |
| Release.ReleaseName | The name of the current release. | Release-47 | |
| Release.ReleaseId | The identifier of the current release record. | 118 | |
| Release.ReleaseUri | The URI of current release. | vstfs:///ReleaseManagement/Release/118 | |
| Release.ReleaseDescription | The text description provided at the time of the release. | Critical security patch | |
| Release.RequestedFor | The display name of identity that triggered the release. | Mateo Escobedo | |
| Release.RequestedForId | The ID of identity that triggered the release. | 2f435d07-769f-4e46-849d-10d1ab9ba6ab | |
| Release.EnvironmentName | The name of environment to which deployment is currently in progress. | Dev | |
| Release.EnvironmentId | The ID of the environment instance in a release to which the deployment is currently in progress. | 276 | |
| Release.EnvironmentUri | The URI of environment instance in a release to which deployment is currently in progress. | vstfs:///ReleaseManagement/Environment/276 | |
| Release.DefinitionEnvironmentId | The ID of the environment in the corresponding release definition. | 1 | TFS 2015 |
| Release.AttemptNumber | The number of times this release is deployed in this environment. | 1 | TFS 2015 |
| Release.Deployment.RequestedFor | The display name of the identity that triggered (started) the deployment currently in progress. | Mateo Escobedo | TFS 2015 |
| Release.Deployment.RequestedForId | The ID of the identity that triggered (started) the deployment currently in progress. | 2f435d07-769f-4e46-849d-10d1ab9ba6ab | TFS 2015 |
Release environment variables
| Variable name | Description | Example | Not available in |
|---|---|---|---|
| Release.Environments.{Environment name}.Status | The status of deployment of this release within a specified environment. | NotStarted | TFS 2015 |
Agent variables
| Variable name | Description | Example | Not available in |
|---|---|---|---|
| Agent.Name | The name of the agent as registered with the agent pool. This is likely to be different from the computer name. | fabrikam-agent | |
| Agent.MachineName | The name of the computer on which the agent is configured. | fabrikam-agent | |
| Agent.Version | The version of the agent software. | 2.109.1 | |
| Agent.JobName | The name of the job that is running, such as Release or Build. | Release | |
| Agent.HomeDirectory | The folder where the agent is installed. This folder contains the code and resources for the agent. | C:\agent | |
| Agent.ReleaseDirectory | The directory to which artifacts are downloaded during deployment of a release. The directory is cleared before every deployment if it requires artifacts to be downloaded to the agent. Same as System.ArtifactsDirectory and System.DefaultWorkingDirectory. | C:\agent_work\r1\a | |
| Agent.RootDirectory | The working directory for this agent, where subfolders are created for every build or release. Same as Agent.WorkFolder and System.WorkFolder. | C:\agent_work | |
| Agent.WorkFolder | The working directory for this agent, where subfolders are created for every build or release. Same as Agent.RootDirectory and System.WorkFolder. | C:\agent_work | |
| Agent.DeploymentGroupId | The ID of the deployment group the agent is registered with. This is available only in deployment group phases. | 1 | TFS 2018 U1 |
General artifact variables
For each artifact that is referenced in a release, you can use the following artifact variables. Not all variables are meaningful for each artifact type. The table below lists the default artifact variables and provides examples of the values that they have depending on the artifact type. If an example is empty, it implies that the variable is not populated for that artifact type.
| Variable name | Description | Team Build example | Jenkins/ TeamCity example | TFVC/Git example | GitHub example |
|---|---|---|---|---|---|
| Release.Artifacts.{alias}.DefinitionId | The identifier of the build definition or repository. | 1 | fabrikam/asp | ||
| Release.Artifacts.{alias}.DefinitionName | The name of the build definition or repository. | fabrikam-ci | TFVC: $/fabrikam, Git: fabrikam | fabrikam/asp (master) | |
| Release.Artifacts.{alias}.BuildNumber | The build number or the commit identifier. | 20170112.1 | 20170112.1 | TFVC: Changeset 3, Git: 38629c964 | 38629c964 |
| Release.Artifacts.{alias}.BuildId | The build identifier. | 130 | 130 | 38629c964d21fe405ef830b7d0220966b82c9e11 | |
| Release.Artifacts.{alias}.BuildURI | The URL for the build. | vstfs:///build-release /Build/130 | |||
| Release.Artifacts.{alias}.SourceBranch | The path of the branch from which the source was built. | refs/heads/master | |||
| Release.Artifacts.{alias}.SourceBranchName | The name of the branch from which the source was built. | master | |||
| Release.Artifacts.{alias}.SourceVersion | The commit that was built. | bc0044458ba1d9298 cdc649cb5dcf013180706f7 | |||
| Release.Artifacts.{alias}.Repository.Provider | The type of repository from which the source was built | Git | |||
| Release.Artifacts.{alias}.RequestedForID | The identifier of the account that triggered the build. | 2f435d07-769f-4e46 -849d-10d1ab9ba6ab | |||
| Release.Artifacts.{alias}.RequestedFor | The name of the account that requested the build. | Mateo Escobedo | |||
| Release.Artifacts.{alias}.Type | The type of artifact source, such as Build. | Build | Jenkins: Jenkins, TeamCity:TeamCity | TFVC: TFVC, Git: Git | GitHub |
See also Artifact source alias
Primary artifact variables
You designate one of the artifacts as a primary artifact in a release definition. For the designated primary artifact, Release Management populates the following variables.
| Variable name | Same as |
|---|---|
| Build.DefinitionId | Release.Artifacts.{Primary artifact alias}.DefinitionId |
| Build.DefinitionName | Release.Artifacts.{Primary artifact alias}.DefinitionName |
| Build.BuildNumber | Release.Artifacts.{Primary artifact alias}.BuildNumber |
| Build.BuildId | Release.Artifacts.{Primary artifact alias}.BuildId |
| Build.BuildURI | Release.Artifacts.{Primary artifact alias}.BuildURI |
| Build.SourceBranch | Release.Artifacts.{Primary artifact alias}.SourceBranch |
| Build.SourceBranchName | Release.Artifacts.{Primary artifact alias}.SourceBranchName |
| Build.SourceVersion | Release.Artifacts.{Primary artifact alias}.SourceVersion |
| Build.Repository.Provider | Release.Artifacts.{Primary artifact alias}.Repository.Provider |
| Build.RequestedForID | Release.Artifacts.{Primary artifact alias}.RequestedForID |
| Build.RequestedFor | Release.Artifacts.{Primary artifact alias}.RequestedFor |
| Build.Type | Release.Artifacts.{Primary artifact alias}.Type |