Edit

Share via

Add & use variable groups

  • Article

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Variable groups store values and secrets that you might want to be passed into a YAML pipeline or make available across multiple pipelines. You can share and use variable groups in multiple pipelines in the same project.

Secret variables in Variables groups are protected resources. You can add combinations of approvals, checks, and pipeline permissions to limit access to secret variables in a variable group. Access to non-secret variables is not limited by approvals, checks, and pipeline permissions.

Create a variable group

You can't create variable groups 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, add a reference to the group in your YAML file:

variables:
- group: my-variable-group

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

If you use both variables and variable groups, use the 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, use macro syntax or a runtime expression. In the following example, the group my-variable-group has a variable named myhello.

variables:
- group: my-variable-group
- name: my-passed-variable
  value: $[variables.myhello] # uses runtime expression

steps:
- script: echo $(myhello) # uses macro syntax
- script: echo $(my-passed-variable)

You can reference multiple variable groups in the same pipeline. If multiple variable groups include the same variable, the variable group included last in your YAML file sets the variable's value.

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 is included and variables.yml is referenced.

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

Authorize a variable group

To work with a variable group, you must authorize the group. If you only 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 authorize the group, use one of the following techniques:

  • To authorize any pipeline to use the variable group, go to Azure Pipelines. This might be a good option if you don't have any secrets in the group. Select Library > Variable groups, and then select the variable group in question and enable the setting Allow access to all pipelines.

  • To authorize a variable group for a specific pipeline, open the pipeline, select Edit, and then queue a build manually. You see a resource authorization error and an "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 add a variable group to a pipeline and don't get a resource authorization error in your build when you expected one, turn off the Allow access to all pipelines setting.

Access the variable values in a linked variable group 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. But, you can't access secret variables (encrypted variables and key vault variables) directly in scripts - instead, they must be passed as arguments to a task. For more information, see secrets

Changes that you make to a variable group are automatically available to all the definitions or stages to which the variable group gets linked.

List variable groups

Use the CLI to list the variable groups for pipeline runs with the az pipelines variable-group list command. If the Azure DevOps extension for CLI is new to you, 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. 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. 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 three 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

Display the details of a variable group in your project with the az pipelines variable-group show command. If the Azure DevOps extension for CLI is new to you, 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. 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. 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

Delete a variable group in your project with the az pipelines variable-group delete command. If the Azure DevOps extension for CLI is new to you, 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. 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. 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.

Add variables to a variable group

With the Azure DevOps CLI, you can add a variable to a variable group in a pipeline with the az pipelines variable-group variable create command. If the Azure DevOps extension for CLI is new to you, 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're adding.
  • org: Azure DevOps organization URL. 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. 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 isn't provided, it's 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. If the Azure DevOps extension for CLI is new to you, 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. 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. 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

Update a variable in a variable group with the az pipelines variable-group variable update command. If the Azure DevOps extension for CLI is new to you, 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're adding.
  • new-name: Optional. Specify to change the name of the variable.
  • org: Azure DevOps organization URL. 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. 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's a secret hidden value.

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

Delete a variable from a variable group with the az pipelines variable-group variable delete command. If the Azure DevOps extension for CLI is new to you, 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're deleting.
  • org: Azure DevOps organization URL. 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. 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.

Note

Key Vaults using Azure role-based access control (Azure RBAC) are not supported.

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. Create a key vault using the Azure portal.

    Screenshot of 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. Enable Azure Pipelines to set these permissions by choosing Authorize next to the vault name. Or, set the permissions manually in the Azure portal:

    1. Open Settings for the vault, and then choose Access policies > Add new.
    2. Select Select principal and then choose the service principal for your client account.
    3. Select Secret permissions and ensure that Get and List have check marks.
    4. Select OK to save the changes.

  3. On the Variable groups page, select + Add to select specific secrets from your vault for mapping to this variable group.

Manage key vault secrets

See the following list of helpful tips for managing secrets.

  • Only the secret names get mapped to the variable group, not the secret values. The latest secret value, fetched from the vault, is used in the pipeline run that's linked to the variable group.

  • Any change made to existing secrets in the key vault is automatically available to all the pipelines the variable group's used in.

  • When new secrets get added to or deleted from the vault, the associated variable groups aren't automatically updated. The secrets included in the variable group must be explicitly updated so the pipelines that are using the variable group get executed 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 aren't supported.

Expand variables in a group

When you set a variable in a group and use it in a YAML file, it's equal to other defined variables in the YAML file. For more information about precedence of variables, see Variables.