Define variables

TFS 2017 | TFS 2015

Note

In Microsoft Team Foundation Server (TFS) 2018 and previous versions, build 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 the pipeline. The most common use of variables is to define a value that you can then use in your pipeline. All variables are stored as strings and are mutable. The value of a variable can change from run to run or job to job of your pipeline.

When you define the same variable in multiple places with the same name, the most locally scoped variable wins. So, a variable defined at the job level can override a variable set at the stage level. A variable defined at the stage level will override a variable set at the pipeline root level. A variable set in the pipeline root level will override a variable set in the Pipeline settings UI.

You can use variables with expressions to conditionally assign values and further customize pipelines.

User-defined variables

When you define a variable, you can use different syntaxes (macro, template expression, or runtime) and what syntax you use will determine where in the pipeline your variable will render.

In YAML pipelines, you can set variables at the root, stage, and job level. You can also specify variables outside of a YAML pipeline in the UI. When you set a variable in the UI, that variable can be encrypted and set as secret.

User-defined variables can be set as read-only. There are naming restrictions for variables (example: you can't use secret at the start of a variable name).

You can use a variable group to make variables available across multiple pipelines.

You can use templates to define variables that are used in multiple pipelines in one file.

System variables

In addition to user-defined variables, Azure Pipelines has system variables with predefined values. If you are using YAML or classic build pipelines, see predefined variables for a comprehensive list of system variables. If you are using classic release pipelines, see release variables.

System variables are set with their current value when you run the pipeline. Some variables are set automatically. As a pipeline author or end user, you change the value of a system variable before the pipeline is run.

System variables are read-only.

Environment variables

Environment variables are specific to the operating system you are using. They are injected into a pipeline in platform-specific ways. The format corresponds to how environment variables get formatted for your specific scripting platform.

On UNIX systems (macOS and Linux), environment variables have the format $NAME. On Windows, the format is %NAME% for batch and $env:NAME in PowerShell.

System and user-defined variables also get injected as environment variables for your platform. When variables are turned into environment variables, variable names become uppercase, and periods turn into underscores. For example, the variable name any.variable becomes the variable name $ANY_VARIABLE.

Variable naming restrictions

User-defined variables can consist of letters, numbers, ., and _ characters. Don't use variable prefixes that are reserved by the system. These are: endpoint, input, secret, and securefile. Any variable that begins with one of these strings (regardless of capitalization) will not be available to your tasks and scripts.

Understand variable syntax

Azure Pipelines supports three different ways to reference variables: macro, template expression, and runtime expression. Each syntax can be used for a different purpose and has some limitations.

In a pipeline, template expression variables (${{ variables.var }}) get processed at compile time, before runtime starts. Macro syntax variables ($(var)) get processed during runtime before a task runs. Runtime expressions ($[variables.var]) also get processed during runtime but were designed for use with conditions and expressions. When you use a runtime expression, it must take up the entire right side of a definition.

In this example, you can see that the template expression still has the initial value of the variable after the variable is updated. The value of the macro syntax variable updates. The template expression value does not change because all template expression variables get processed at compile time before tasks run. In contrast, macro syntax variables are evaluated before each task runs.

variables:
- name: one
  value: initialValue 

steps:
  - script: |
      echo ${{ variables.one }} # outputs initialValue
      echo $(one)
    displayName: First variable pass
  - bash: echo "##vso[task.setvariable variable=one]secondValue"
    displayName: Set new variable value
  - script: |
      echo ${{ variables.one }} # outputs initialValue
      echo $(one) # outputs secondValue
    displayName: Second variable pass

Macro syntax variables

Most documentation examples use macro syntax ($(var)). Macro syntax is designed to interpolate variable values into task inputs and into other variables.

Variables with macro syntax get processed before a task executes during runtime. Runtime happens after template expansion. When the system encounters a macro expression, it replaces the expression with the contents of the variable. If there's no variable by that name, then the macro expression is left unchanged. For example, if $(var) can't be replaced, $(var) won't be replaced by anything.

Macro syntax variables remain unchanged with no value because an empty value like $() might mean something to the task you are running and the agent should not assume you want that value replaced. For example, if you use $(foo) to reference variable foo in a Bash task, replacing all $() expressions in the input to the task could break your Bash scripts.

Macro variables are only expanded when they are used for a value, not as a keyword. Values appear on the right side of a pipeline definition. The following is valid: key: $(value). The following isn't valid: $(key): value. Macro variables are not expanded when used to display a job name inline. Instead, you must use the displayName property.

Note

Macro syntax variables are only expanded for stages, jobs, and steps. You cannot, for example, use macro syntax inside a resource or trigger.

In this example, macro syntax is used with Bash, PowerShell, and a script task. The syntax for calling a variable with macro syntax is the same for all three.

variables:
 - name: projectName
   value: contoso

steps: 
- bash: echo $(projectName)
- powershell: echo $(projectName)
- script: echo $(projectName)

Template expression syntax

You can use template expression syntax to expand both template parameters and variables (${{ variables.var }}). Template variables are processed at compile time, and are replaced before runtime starts. Template expressions are designed for reusing parts of YAML as templates.

Template variables silently coalesce to empty strings when a replacement value isn't found. Template expressions, unlike macro and runtime expressions, can appear as either keys (left side) or values (right side). The following is valid: ${{ variables.key }} : ${{ variables.value }}.

Runtime expression syntax

You can use runtime expression syntax for variables that are expanded at runtime ($[variables.var]). Runtime expression variables silently coalesce to empty strings when a replacement value isn't found. Runtime expressions are designed to be used in the conditions of jobs, to support conditional execution of jobs, or whole stages.

Runtime expression variables are only expanded when they are used for a value, not as a keyword. Values appear on the right side of a pipeline definition. The following is valid: key: $[variables.value]. The following isn't valid: $[variables.key]: value. The runtime expression must take up the entire right side of a key-value pair. For example, key: $[variables.value] is valid but key: $[variables.value] foo is not.

Syntax	Example	When is it processed?	Where does it expand in a pipeline definition?	How does it render when not found?
macro	$(var)	runtime before a task executes	value (right side)	prints $(var)
template expression	${{ variables.var }}	compile time	key or value (left or right side)	empty string
runtime expression	$[variables.var]	runtime	value (right side)	empty string

What syntax should I use?

Use macro syntax if you are providing input for a task.

Choose a runtime expression if you are working with conditions and expressions. The exception to this is if you have a pipeline where it will cause a problem for your empty variable to print out. For example, if you have conditional logic that relies on a variable having a specific value or no value. In that case, you should use a runtime expression.

If you are defining a variable in a template, use a template expression.

Set variables in pipeline

YAML

YAML is not supported in TFS.

Classic

You can set a variable for a build pipeline by following these steps:

1. Go to the Pipelines page, select the appropriate pipeline, and then select Edit.
2. Locate the Variables for this pipeline.
3. Add or update the variable.
4. To mark the variable as secret, select Keep this value secret.
5. Save the pipeline.

After the variable is set, you can use it as an input to a task or within the scripts in your pipeline. To use a variable as an input to a task, wrap it in $().

Notice that variables are also made available to scripts through environment variables. The syntax for using these environment variables depends on the scripting language.

The name is upper-cased, and the . is replaced with the _. This is automatically inserted into the process environment. Here are some examples:

• Batch script: %VARIABLE_NAME%
• PowerShell script: $env:VARIABLE_NAME
• Bash script: $VARIABLE_NAME

Important

Predefined variables that contain file paths are translated to the appropriate styling (Windows style C:\foo\ versus Unix style /foo/) based on agent host type and shell type. If you are running bash script tasks on Windows, you should use the environment variable method for accessing these variables rather than the pipeline variable method to ensure you have the correct file path styling.

Azure DevOps CLI

Azure DevOps CLI commands aren't supported for Azure DevOps Server on-premises versions.

Set secret variables

YAML

YAML is not supported in TFS.

Classic

To set secrets in the web interface, follow these steps:

1. Go to the Pipelines page, select the appropriate pipeline, and then select Edit.
2. Locate the Variables for this pipeline.
3. Add or update the variable.
4. Select the lock icon to store the variable in an encrypted manner.
5. Save the pipeline.

Secret variables are encrypted at rest with a 2048-bit RSA key. Secrets are available on the agent for tasks and scripts to use. Be careful about who has access to alter your pipeline.

Important

We make an effort to mask secrets from appearing in Azure Pipelines output, but you still need to take precautions. Never echo secrets as output. Some operating systems log command line arguments. Never pass secrets on the command line. Instead, we suggest that you map your secrets into environment variables.

We never mask substrings of secrets. If, for example, "abc123" is set as a secret, "abc" isn't masked from the logs. This is to avoid masking secrets at too granular of a level, making the logs unreadable. For this reason, secrets should not contain structured data. If, for example, "{ "foo": "bar" }" is set as a secret, "bar" isn't masked from the logs.

Unlike a normal variable, they are not automatically decrypted into environment variables for scripts. You need to explicitly map secret variables.

Each task that needs to use the secret as an environment variable does remapping. If you want to use a secret variable called mySecret from a script, use the Environment section of the scripting task's input variables. Set the environment variable name to MYSECRET, and set the value to $(mySecret).

Important

By default with GitHub repositories, secret variables associated with your pipeline aren't made available to pull request builds of forks. For more information, see Contributions from forks.

Azure DevOps CLI

Azure DevOps CLI commands aren't supported for Azure DevOps Server on-premises versions.

Share variables across pipelines

To share variables across multiple pipelines in your project, use the web interface. Under Library, use variable groups.

Use output variables from tasks

Some tasks define output variables, which you can consume in downstream steps within the same job.

• To reference a variable from a different task within the same job, use TASK.VARIABLE.
• To reference a variable from a task from a different job, use dependencies.JOB.outputs['TASK.VARIABLE'].

Note

By default, each stage in a pipeline depends on the one just before it in the YAML file. If you need to refer to a stage that isn't immediately prior to the current one, you can override this automatic default by adding a dependsOn section to the stage.

Note

The following examples use standard pipeline syntax. If you're using deployment pipelines, both variable and conditional variable syntax will differ. For information about the specific syntax to use, see Deployment jobs.

YAML

For these examples, assume we have a task called MyTask, which sets an output variable called MyVar. Learn more about the syntax in Expressions - Dependencies.

Use outputs in the same job

steps:
- task: MyTask@1  # this step generates the output variable
  name: ProduceVar  # because we're going to depend on it, we need to name the step
- script: echo $(ProduceVar.MyVar) # this step uses the output variable

Use outputs in a different job

jobs:
- job: A
  steps:
  # assume that MyTask generates an output variable called "MyVar"
  # (you would learn that from the task's documentation)
  - task: MyTask@1
    name: ProduceVar  # because we're going to depend on it, we need to name the step
- job: B
  dependsOn: A
  variables:
    # map the output variable from A into this job
    varFromA: $[ dependencies.A.outputs['ProduceVar.MyVar'] ]
  steps:
  - script: echo $(varFromA) # this step uses the mapped-in variable

Classic

Use outputs in the same job

In the Output variables section, give the producing task a reference name. Then, in a downstream step, you can use the form $(<ReferenceName>.<VariableName>) to refer to output variables.

Use outputs in a different job

You must use YAML to consume output variables in a different job.

Azure DevOps CLI

Azure DevOps CLI commands aren't supported for Azure DevOps Server on-premises versions.

Set variables in scripts

A script in your pipeline can define a variable so that it can be consumed by one of the subsequent steps in the pipeline. All variables set by this method are treated as strings. To set a variable from a script, you use a command syntax and print to stdout.

YAML

YAML is not supported in TFS.

Classic

Set a job-scoped variable from a script

To set a variable from a script, use the task.setvariable logging command. This doesn't update the environment variables, but it does make the new variable available to downstream steps within the same job.

Tip

You can run a script on a:

• Windows agent using either a Batch script task or PowerShell script task.
• macOS or Linux agent using a Shell script task.

Batch

Batch script

Set the sauce and secret.Sauce variables

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

Read the variables

Arguments

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

Script

@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)

PowerShell

PowerShell script

Set the sauce and secret.Sauce variables

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

Read the variables

Arguments

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

Script

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)"

Shell

Set the sauce and secret.Sauce variables

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

Read the variables

Arguments

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

Script

#!/bin/bash
echo "No problem reading $1 or $SAUCE"
echo "But I cannot read $SECRET_SAUCE"
echo "But I can read $2 (but the log is redacted so I do not spoil the secret)"

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)

Use variables as task inputs

In order to use a variable as a task input, you must make the variable an output variable, and you must give the producing task a reference name. You can set a task's reference name on the Output Variables section of the task editor. For instance, a script task whose output variable reference name is producer might have the following contents:

mkdir myDir
echo ##vso[task.setvariable variable=newworkdir;isOutput=true]$(System.DefaultWorkingDirectory)\myDir

The output variable newworkdir can be referenced in the input of a downstream task as $(producer.newworkdir).

Set a multi-job output variable

You can't pass a variable from one job to another job of a build pipeline, unless you use YAML.

Azure DevOps CLI

Azure DevOps CLI commands aren't supported for Azure DevOps Server on-premises versions.

Set variables by using expressions

YAML

YAML is not supported in TFS.

Classic

You can use any of the supported expressions for setting a variable. Here's an example of setting a variable to act as a counter that starts at 100, gets incremented by 1 for every run, and gets reset to 100 every day.

• In the variables of a build pipeline, set a variable a to this value: $[counter(format('{0:yyyyMMdd}', pipeline.startTime), 100)]

For more information about counters and other expressions, see expressions.

Azure DevOps CLI

Azure DevOps CLI commands aren't supported for Azure DevOps Server on-premises versions.

Allow at queue time

YAML

YAML is not supported in TFS.

Classic

You can choose which variables are allowed to be set at queue time, and which are fixed by the pipeline author. To do this, select the variable in the Variables tab of the build pipeline, and mark it as Settable at release time.

Azure DevOps CLI

Azure DevOps CLI commands aren't supported for Azure DevOps Server on-premises versions.

Expansion of variables

YAML

YAML is not supported in TFS.

Classic

When you set a variable with the same name in multiple scopes, the following precedence applies (highest precedence first).

1. Variable set at queue time
2. Variable set in the pipeline
3. Variable set in the variable group

Variables are expanded once when the run is started, and again at the beginning of each step. Here's an example to demonstrate this:

• You set a variable called a to 10 in a pipeline.

• In one of the steps (a bash script step), run the following script:

  echo $(a)            # This will be 10
  echo '##vso[task.setvariable variable=a]20'
  echo $(a)            # This will also be 10, since the expansion of $(a) happens before the step
  

• In the next step (another bash script step), run the following script:

  echo $(a)            # This will be 20, since the variables are expanded just before the step
  

Azure DevOps CLI

Azure DevOps CLI commands aren't supported for Azure DevOps Server on-premises versions.