Use variables in Classic release pipelines

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022

Using variables in Classic release pipelines is a convenient way to exchange and transport data throughout your pipeline. Each variable is stored as a string, and its value can change between pipeline runs.

When you set up tasks to deploy your application in each stage of your Classic release pipeline, variables can help you:

• Simplify customization: Define a generic deployment pipeline once and easily adapt it for different stages. For instance, use a variable to represent a web deployment's connection string, adjusting its value as needed for each stage. These variables are known as custom variables.

• Leverage contextual information: Access details about the release context, such as a stage, an artifact, or the agent running the deployment. For example, your scripts might require the build location for download, or the agent's working directory to create temporary files. These variables are referred to as default variables.

Default variables

Default variables provide essential information about the execution context to your running tasks and scripts. These variables give you access to details about the system, release, stage, or agent in which they're running.

With the exception of System.Debug, default variables are read-only, and the system automatically sets their values.

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 variables

Release variables

Release-stage variables

Agent variables

Release artifacts variables

For each artifact that you reference in a release, use the following artifact variables. Note that not all variables apply to every artifact type. The following table lists default artifact variables and provides examples of their values based on the artifact type. If an example is empty, it indicates that the variable isn't applicable for that artifact type.

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

Primary artifact variables

In Classic release pipelines, if you use multiple artifacts, you can designate one artifact as the primary artifact. Azure Pipelines then populates the following variables for the designated primary artifact.

Use default variables

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

Use a default variable directly as an input to a task. For example, to pass Release.Artifacts.{Artifact alias}.DefinitionName as an argument to a PowerShell task for an artifact with ASPNET4.CI as its alias, use $(Release.Artifacts.ASPNET4.CI.DefinitionName).

To use a default variable in your script, replace the . in the default variable names with _. For example, to print the value of Release.Artifacts.{Artifact alias}.DefinitionName for an artifact with ASPNET4.CI as its alias in a PowerShell script, use $env:RELEASE_ARTIFACTS_ASPNET4_CI_DEFINITIONNAME. The original alias, ASPNET4.CI, is replaced with ASPNET4_CI.

Custom variables

You can define custom variables at different scopes.

• Variable Groups: Use variable groups to share values across all definitions in a project. This approach is useful when you want to use the same values throughout definitions, stages, and tasks within a project, and manage them from a single location. Define and manage variable groups in the Pipelines > Library.

• Release Pipeline Variables: Use release pipeline variables to share values across all stages within a release pipeline. This approach is ideal for scenarios where you need a consistent value across stages and tasks, with the ability to update it from a single location. Define and manage these variables in the Variables tab of the release pipeline. In the Pipeline Variables page, set the Scope drop-down list to Release when adding a variable.

• Stage Variables: Use stage variables to share values within a specific stage of a release pipeline. This approach is useful for values that differ from stage to stage but are consistent across all tasks within a stage. Define and manage these variables in the Variables tab of the release pipeline. In the Pipeline Variables page, set the Scope drop-down list to appropriate environment when adding a variable.

By using custom variables at the project, release pipeline, and stage levels, you can:

• Avoid duplicating values, making it easier to update all occurrences with a single change.

• Secure sensitive values by preventing them from being viewed or modified by users. To mark a variable as secure (secret), select the icon next to the variable.

  Important

  The values of the hidden variables (secret) are securely stored on the server and users can't view them after they're saved. During deployment, Azure Pipelines decrypts these values when tasks reference them and passes them to the agent over a secure HTTPS channel.

Use custom variables

To use custom variables in your tasks, enclose the variable name in parentheses and precede it with a $ character. For example, if you have a variable named adminUserName, insert its current value into 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. The updated variable value is scoped to the job being executed and doesn't persist across jobs or stages. Note that variable names are transformed to uppercase, with "." and " " replaced with "_".

For example, Agent.WorkFolder becomes AGENT_WORKFOLDER.

• On Windows, access this variable as %AGENT_WORKFOLDER% or $env:AGENT_WORKFOLDER.
• On Linux and macOS, 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)"

- pwsh: |
      Write-Host No problem reading $(sauce)
      Write-Host But I cannot read $env:SECRET_SAUCE
      Write-Host But I can read $(secret.Sauce) "(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)

View the current values of all variables

1. Select Pipelines > Releases, and then select your release pipeline.

2. Open the summary view for your release, and select the stage you're interested in. In the list of steps, choose Initialize job.

   

3. This step opens the logs. Scroll down to see the values the agent uses for this job.

   

Run a release in debug mode

Running a release in debug mode can help you diagnose and resolve problems by displaying extra information during the release execution. You can turn on debug mode for the whole release or just for the tasks in a specific release stage.

• To turn on debug mode for the whole release, add a variable named System.Debug with the value true to the Variables tab of the release pipeline.

• To turn on debug mode for a specific 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 the release pipeline.

Related content

• Artifact sources in Classic release pipelines

• Deploy pull request Artifacts

• Use variables in a variable group