Add & use variable groups

Use a variable group to store values that you want to control and make available across multiple pipelines. You can also use variable groups to store secrets and other values that might need to be passed into a YAML pipeline. Variable groups are defined and managed in the Library page under Pipelines.

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.

Note

Variable groups can be used in a build pipeline in only Azure DevOps and TFS 2018. They cannot be used in a build pipeline in earlier versions of TFS.

Create a variable group

Variable groups can't be created in YAML, but they can be used as described in Use a variable group.

Use a variable group

To use a variable from a variable group, you need to add a reference to the group in your YAML file:

variables:
- group: my-variable-group

Thereafter variables from the variable group can be used in your YAML file.

If you use both variables and variable groups, you'll have to use name/value syntax for the individual (non-grouped) variables:

variables:
- group: my-variable-group
- name: my-bare-variable
  value: 'value of my-bare-variable'

To reference a variable group, you can use macro syntax or a runtime expression. In this example, the group my-variable-group has a variable named myhello.

variables:
- group: my-variable-group

steps:
- script: echo $(myhello) # uses macro syntax
- script: echo $[variables.myhello] # uses runtime expression

You can reference multiple variable groups in the same pipeline.

variables:
- group: my-first-variable-group
- group: my-second-variable-group

You can also reference a variable group in a template. In the template variables.yml, the group my-variable-group is referenced. The variable group includes a variable named myhello.

# variables.yml
variables:
- group: my-variable-group

In this pipeline, the variable $(myhello) from the variable group my-variable-group included in variables.yml is referenced.

# azure-pipeline.yml
stages:
- stage: MyStage
  variables:
  - template: variables.yml
  jobs:
  - job: Test
    steps:
    - script: echo $(myhello)

To work with variable groups, you must authorize the group. This is a security feature: if you only had to name the variable group in YAML, then anyone who can push code to your repository could extract the contents of secrets in the variable group. To do this, or if you encounter a resource authorization error in your build, use one of the following techniques:

  • If you want to authorize any pipeline to use the variable group, which may be a suitable option if you do not have any secrets in the group, go to Azure Pipelines, open the Library page, choose Variable groups, select the variable group in question, and enable the setting Allow access to all pipelines.

  • If you want to authorize a variable group for a specific pipeline, open the pipeline by selecting Edit and queue a build manually. You will see a resource authorization error and a "Authorize resources" action on the error. Choose this action to explicitly add the pipeline as an authorized user of the variable group.

Note

If you added a variable group to a pipeline and did not get a resource authorization error in your build when you expected one, turn off the Allow access to all pipelines setting described above.

YAML builds are not yet available on TFS.

You access the value of the variables in a linked variable group in exactly the same way as variables you define within the pipeline itself. For example, to access the value of a variable named customer in a variable group linked to the pipeline, use $(customer) in a task parameter or a script. However, secret variables (encrypted variables and key vault variables) cannot be accessed directly in scripts - instead they must be passed as arguments to a task. For more information, see secrets

Any changes made centrally to a variable group, such as a change in the value of a variable or the addition of new variables, will automatically be made available to all the definitions or stages to which the variable group is linked.

Manage a variable group

Using the Azure DevOps CLI, you can list the variable groups for the pipeline runs in your project and show details for each one. You can also delete variable groups if you no longer need them.

List variable groups | Show details for a variable group | Delete a variable group

List variable groups

You can list the variable groups in your project with the az pipelines variable-group list command. To get started, see Get started with Azure DevOps CLI.

az pipelines variable-group list [--action {manage, none, use}]
                                 [--continuation-token]
                                 [--group-name]
                                 [--org]
                                 [--project]
                                 [--query-order {Asc, Desc}]
                                 [--top]

Optional parameters

  • action: Specifies the action that can be performed on the variable groups. Accepted values are manage, none and use.
  • continuation-token: Lists the variable groups after a continuation token is provided.
  • group-name: Name of the variable group. Wildcards are accepted, such as new-var*.
  • org: Azure DevOps organization URL. You can configure the default organization using az devops configure -d organization=ORG_URL. Required if not configured as default or picked up using git config. Example: --org https://dev.azure.com/MyOrganizationName/.
  • project: Name or ID of the project. You can configure the default project using az devops configure -d project=NAME_OR_ID. Required if not configured as default or picked up using git config.
  • query-order: Lists the results in either ascending or descending (the default) order. Accepted values are Asc and Desc.
  • top: Number of variable groups to list.

Example

The following command lists the top 3 variable groups in ascending order and returns the results in table format.

az pipelines variable-group list --top 3 --query-order Asc --output table

ID    Name               Type    Number of Variables
----  -----------------  ------  ---------------------
1     myvariables        Vsts    2
2     newvariables       Vsts    4
3     new-app-variables  Vsts    3

Show details for a variable group

You can display the details of a variable group in your project with the az pipelines variable-group show command. To get started, see Get started with Azure DevOps CLI.

az pipelines variable-group show --group-id
                                 [--org]
                                 [--project]

Parameters

  • group-id: Required. ID of the variable group. To find the variable group ID, see List variable groups.
  • org: Azure DevOps organization URL. You can configure the default organization using az devops configure -d organization=ORG_URL. Required if not configured as default or picked up using git config. Example: --org https://dev.azure.com/MyOrganizationName/.
  • project: Name or ID of the project. You can configure the default project using az devops configure -d project=NAME_OR_ID. Required if not configured as default or picked up using git config.

Example

The following command shows details for the variable group with the ID 4 and returns the results in YAML format.

az pipelines variable-group show --group-id 4 --output yaml

authorized: false
description: Variables for my new app
id: 4
name: MyNewAppVariables
providerData: null
type: Vsts
variables:
  app-location:
    isSecret: null
    value: Head_Office
  app-name:
    isSecret: null
    value: Fabrikam

Delete a variable group

You can delete a variable group in your project with the az pipelines variable-group delete command. To get started, see Get started with Azure DevOps CLI.

az pipelines variable-group delete --group-id
                                   [--org]
                                   [--project]
                                   [--yes]

Parameters

  • group-id: Required. ID of the variable group. To find the variable group ID, see List variable groups.
  • org: Azure DevOps organization URL. You can configure the default organization using az devops configure -d organization=ORG_URL. Required if not configured as default or picked up using git config. Example: --org https://dev.azure.com/MyOrganizationName/.
  • project: Name or ID of the project. You can configure the default project using az devops configure -d project=NAME_OR_ID. Required if not configured as default or picked up using git config.
  • yes: Optional. Doesn't prompt for confirmation.

Example

The following command deletes the variable group with the ID 1 and doesn't prompt for confirmation.

az pipelines variable-group delete --group-id 1 --yes

Deleted variable group successfully.

Manage variables in a variable group

Using the Azure DevOps CLI, you can add and delete variables from a variable group in a pipeline run. You can also list the variables in the variable group and make updates to them as needed.

Add variables to a variable group | List variables in a variable group | Update variables in a variable group | Delete variables from a variable group

Add variables to a variable group

You can add a variable to a variable group with the az pipelines variable-group variable create command. To get started, see Get started with Azure DevOps CLI.

az pipelines variable-group variable create --group-id
                                            --name
                                            [--org]
                                            [--project]
                                            [--secret {false, true}]
                                            [--value]

Parameters

  • group-id: Required. ID of the variable group. To find the variable group ID, see List variable groups.
  • name: Required. Name of the variable you are adding.
  • org: Azure DevOps organization URL. You can configure the default organization using az devops configure -d organization=ORG_URL. Required if not configured as default or picked up using git config. Example: --org https://dev.azure.com/MyOrganizationName/.
  • project: Name or ID of the project. You can configure the default project using az devops configure -d project=NAME_OR_ID. Required if not configured as default or picked up using git config.
  • secret: Optional. Indicates whether the variable's value is a secret. Accepted values are false and true.
  • value: Required for non secret variable. Value of the variable. For secret variables, if value parameter is not provided, it is picked from environment variable prefixed with AZURE_DEVOPS_EXT_PIPELINE_VAR_ or user is prompted to enter it via standard input. For example, a variable named MySecret can be input using the environment variable AZURE_DEVOPS_EXT_PIPELINE_VAR_MySecret.

Example

The following command creates a variable in the variable group with ID of 4. The new variable is named requires-login and has a value of True, and the result is shown in table format.

az pipelines variable-group variable create --group-id 4 --name requires-login --value True --output table

Name            Is Secret    Value
--------------  -----------  -------
requires-login  False        True

List variables in a variable group

You can list the variables in a variable group with the az pipelines variable-group variable list command. To get started, see Get started with Azure DevOps CLI.

az pipelines variable-group variable list --group-id
                                          [--org]
                                          [--project]

Parameters

  • group-id: Required. ID of the variable group. To find the variable group ID, see List variable groups.
  • org: Azure DevOps organization URL. You can configure the default organization using az devops configure -d organization=ORG_URL. Required if not configured as default or picked up using git config. Example: --org https://dev.azure.com/MyOrganizationName/.
  • project: Name or ID of the project. You can configure the default project using az devops configure -d project=NAME_OR_ID. Required if not configured as default or picked up using git config.

Example

The following command lists all of the variables in the variable group with ID of 4 and shows the result in table format.

az pipelines variable-group variable list --group-id 4 --output table

Name            Is Secret    Value
--------------  -----------  -----------
app-location    False        Head_Office
app-name        False        Fabrikam
requires-login  False        True

Update variables in a variable group

You can update a variable in a variable group with the az pipelines variable-group variable update command. To get started, see Get started with Azure DevOps CLI.

az pipelines variable-group variable update --group-id
                                            --name
                                            [--new-name]
                                            [--org]
                                            [--project]
                                            [--prompt-value {false, true}]
                                            [--secret {false, true}]
                                            [--value]

Parameters

  • group-id: Required. ID of the variable group. To find the variable group ID, see List variable groups.
  • name: Required. Name of the variable you are adding.
  • new-name: Optional. Specify to change the name of the variable.
  • org: Azure DevOps organization URL. You can configure the default organization using az devops configure -d organization=ORG_URL. Required if not configured as default or picked up using git config. Example: --org https://dev.azure.com/MyOrganizationName/.
  • project: Name or ID of the project. You can configure the default project using az devops configure -d project=NAME_OR_ID. Required if not configured as default or picked up using git config.
  • prompt-value: Set to true to update the value of a secret variable using environment variable or prompt via standard input. Accepted values are false and true.
  • secret: Optional. Indicates whether the variable's value is kept secret. Accepted values are false and true.
  • value: Updates the value of the variable. For secret variables, use the prompt-value parameter to be prompted to enter it via standard input. For non-interactive consoles, it can be picked from environment variable prefixed with AZURE_DEVOPS_EXT_PIPELINE_VAR_. For example, a variable named MySecret can be input using the environment variable AZURE_DEVOPS_EXT_PIPELINE_VAR_MySecret.

Example

The following command updates the requires-login variable with the new value False in the variable group with ID of 4. It specifies that the variable is a secret and shows the result in YAML format. Notice that the output shows the value as null instead of False since it is a secret value (hidden).

az pipelines variable-group variable update --group-id 4 --name requires-login --value False --secret true --output yaml

requires-login:
  isSecret: true
  value: null

Delete variables from a variable group

You can delete a variable from a variable group with the az pipelines variable-group variable delete command. To get started, see Get started with Azure DevOps CLI.

az pipelines variable-group variable delete --group-id
                                            --name
                                            [--org]
                                            [--project]
                                            [--yes]

Parameters

  • group-id: Required. ID of the variable group. To find the variable group ID, see List variable groups.
  • name: Required. Name of the variable you are deleting.
  • org: Azure DevOps organization URL. You can configure the default organization using az devops configure -d organization=ORG_URL. Required if not configured as default or picked up using git config. Example: --org https://dev.azure.com/MyOrganizationName/.
  • project: Name or ID of the project. You can configure the default project using az devops configure -d project=NAME_OR_ID. Required if not configured as default or picked up using git config.
  • yes: Optional. Doesn't prompt for confirmation.

Example

The following command deletes the requires-login variable from the variable group with ID of 4 and prompts for confirmation.

az pipelines variable-group variable delete --group-id 4 --name requires-login

Are you sure you want to delete this variable? (y/n): y
Deleted variable 'requires-login' successfully.

Link an existing Azure key vault to a variable group and map selective vault secrets to the variable group.

  1. In the Variable groups page, enable Link secrets from an Azure key vault as variables. You'll need an existing key vault containing your secrets. You can create a key vault using the Azure portal.

    Variable group with Azure key vault integration

  2. Specify your Azure subscription end point and the name of the vault containing your secrets.

    Ensure the Azure service connection has at least Get and List management permissions on the vault for secrets. You can enable Azure Pipelines to set these permissions by choosing Authorize next to the vault name. Alternatively, you can set the permissions manually in the Azure portal:

    • Open the Settings blade for the vault, choose Access policies, then Add new.
    • In the Add access policy blade, choose Select principal and select the service principal for your client account.
    • In the Add access policy blade, choose Secret permissions and ensure that Get and List are checked (ticked).
    • Choose OK to save the changes.

  3. In the Variable groups page, choose + Add to select specific secrets from your vault that will be mapped to this variable group.

Secrets management notes

  • Only the secret names are mapped to the variable group, not the secret values. The latest version of the value of each secret is fetched from the vault and used in the pipeline linked to the variable group during the run.

  • Any changes made to existing secrets in the key vault, such as a change in the value of a secret, will be made available automatically to all the pipelines in which the variable group is used.

  • When new secrets are added to the vault, or a secret is deleted from the vault, the associated variable groups are not updated automatically. The secrets included in the variable group must be explicitly updated in order for the pipelines using the variable group to execute correctly.

  • Azure Key Vault supports storing and managing cryptographic keys and secrets in Azure. Currently, Azure Pipelines variable group integration supports mapping only secrets from the Azure key vault. Cryptographic keys and certificates are not supported.

Expansion of variables in a group

When you set a variable in a group and use it in a YAML file, it has the same precedence as any other variable defined within the YAML file. For more information about precedence of variables, see the topic on variables.

YAML is not supported in TFS.