Classic release and artifacts variables

TFS 2017 | TFS 2015

As you compose the tasks for deploying your application into each stage in your DevOps CI/CD processes, variables will help you to:

• Define a more generic deployment pipeline once, and then customize it easily for each stage. 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 stage to another. These are custom variables.

• Use information about the context of the particular release, stage, artifacts, or agent in which the deployment pipeline 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.

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, stage, 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. To view the full list, see View the current values of all variables.

System

Release

Release-stage

Agent

General Artifact

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.

Replace the {alias} placeholder with the value you specified for the artifact alias or with the default value generated for the release pipeline.

See also Artifact source alias

Primary Artifact

You designate one of the artifacts as a primary artifact in a release pipeline. For the designated primary artifact, Azure Pipelines populates the following variables.

Use default variables

You can use the default variables in two ways - as parameters to tasks in a release pipeline or in your scripts.

You can directly use a default variable as an input to a task. For example, to pass Release.Artifacts.{Artifact alias}.DefinitionName for the artifact source whose alias is ASPNET4.CI to a task, you would use $(Release.Artifacts.ASPNET4.CI.DefinitionName).

To use a default variable in your script, you must first replace the . in the default variable names with _. For example, to print the value of artifact variable Release.Artifacts.{Artifact alias}.DefinitionName for the artifact source whose alias is ASPNET4.CI in a PowerShell script, you would use $env:RELEASE_ARTIFACTS_ASPNET4_CI_DEFINITIONNAME.

Note that the original name of the artifact source alias, ASPNET4.CI, is replaced by ASPNET4_CI.

View the current values of all variables

1. Open the pipelines view of the summary for the release, and choose the stage you are interested in. In the list of steps, choose Initialize job.

   

2. This opens the log for this step. Scroll down to see the values used by the agent for this job.

   

Run a release in debug mode

Show additional information as a release executes and in the log files by running the entire release, or just the tasks in an individual release stage, in debug mode. This can help you resolve issues and failures.

• To initiate debug mode for an entire release, add a variable named System.Debug with the value true to the Variables tab of a release pipeline.

• To initiate debug mode for a single stage, open the Configure stage dialog from the shortcut menu of the stage and add a variable named System.Debug with the value true to the Variables tab.

• Alternatively, create a variable group containing a variable named System.Debug with the value true and link this variable group to a release pipeline.

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, stages, 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 stages by using release pipeline variables. Choose a release pipeline variable when you need to use the same value across all the stages and tasks in the release pipeline, 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 pipeline. In the Pipeline Variables page, open the Scope drop-down list and select "Release". By default, when you add a variable, it is set to Release scope.

• Share values across all of the tasks within one specific stage by using stage variables. Use a stage-level variable for values that vary from stage to stage (and are the same for all the tasks in an stage). You define and manage these variables in the Variables tab of a release pipeline. In the Pipeline Variables page, open the Scope drop-down list and select the required stage. When you add a variable, set the Scope to the appropriate environment.

Using custom variables at project, release pipeline, and stage 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 pipelines. Designate a configuration property to be a secure (secret) variable by selecting the (padlock) icon next to the variable.

  Important

  The values of the hidden (secret) variables are securely stored on the server and cannot be viewed by users after they are saved. During a deployment, the Azure Pipelines release service decrypts these values when referenced by the tasks and passes them to the agent over a secure HTTPS channel.

Use custom variables

To use custom variables in your build and release tasks, simply enclose the variable name in parentheses and precede it with a $ character. For example, if you have a variable named adminUserName, you can insert the current value of that variable into a parameter of a task as $(adminUserName).

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 job being executed, and does not flow across jobs or stages. Variable names are transformed to uppercase, and the characters "." and " " are replaced by "_".

For example, Agent.WorkFolder becomes AGENT_WORKFOLDER. On Windows, you access this as %AGENT_WORKFOLDER% or $env:AGENT_WORKFOLDER. On Linux and macOS, you use $AGENT_WORKFOLDER.

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

"$(sauce)" "$(secret.Sauce)"

@echo off
set sauceArgument=%~1
set secretSauceArgument=%~2
@echo No problem reading %sauceArgument% or %SAUCE%
@echo But I cannot read %SECRET_SAUCE%
@echo But I can read %secretSauceArgument% (but the log is redacted so I do not spoil
     the secret)

Write-Host "##vso[task.setvariable variable=sauce]crushed tomatoes"
Write-Host "##vso[task.setvariable variable=secret.Sauce;issecret=true]crushed tomatoes with
            garlic"

-sauceArgument "$(sauce)" -secretSauceArgument "$(secret.Sauce)"

Param(
   [string]$sauceArgument,
   [string]$secretSauceArgument
)
Write-Host No problem reading $env:SAUCE or $sauceArgument
Write-Host But I cannot read $env:SECRET_SAUCE
Write-Host But I can read $secretSauceArgument "(but the log is redacted so I do not
           spoil the secret)"

#!/bin/bash
echo "##vso[task.setvariable variable=sauce]crushed tomatoes"
echo "##vso[task.setvariable variable=secret.Sauce;issecret=true]crushed tomatoes with garlic"

"$(sauce)" "$(secret.Sauce)"

#!/bin/bash
echo "No problem reading $SAUCE"
echo "But I cannot read $SECRET_SAUCE"

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)