Manage variable groups

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

This article explains how to create and use variable groups in Azure Pipelines. Variable groups store values and secrets that you can pass into a YAML pipeline or make available across multiple pipelines in a project.

Secret variables in variable 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 nonsecret variables isn't limited by approvals, checks, or pipeline permissions.

Variable groups follow the library security model for roles and permissions.

Prerequisites

• An Azure DevOps Services organization and project where you have permissions to create pipelines and variables.
• A project in your Azure DevOps organization or Azure DevOps Server collection. Create a project if you don't have one.
• If you're using the Azure DevOps CLI, you need Azure CLI version 2.30.0 or higher with the Azure DevOps CLI extension. For more information, see Get started with Azure DevOps CLI.

Set up the CLI

If you're using the Azure DevOps CLI, you need to set up the CLI to work with your Azure DevOps organization and project.

1. Sign in to your Azure DevOps organization by using the az login command.

   az login
   

2. If prompted, select your subscription from the list displayed in your terminal window.

3. Ensure you're running the latest version of the Azure CLI and the Azure DevOps extension by using the following commands.

   az upgrade
   az extension add --name azure-devops --upgrade
   

4. In Azure DevOps CLI commands, you can set the default organization and project by using:

   az devops configure --defaults organization=<YourOrganizationURL> project=<Project Name or ID>`
   

   If you haven't set the default organization and project, you can use the detect=true parameter in your commands to automatically detect the organization and project context based on your current directory. If the defaults aren't configured or detected, you need to explicitly specify the org and project parameters in your commands.

Create a variable group

You can create variable groups for the pipeline runs in your project.

Note

To create a secret variable group to link secrets from an Azure key vault as variables, follow the instructions at Link a variable group to secrets in Azure Key Vault.

Azure Pipelines UI

1. In your Azure DevOps project, select Pipelines > Library from the left menu.

2. On the Library page, select + Variable group.

   

3. On the new variable group page, under Properties, enter a name and optional description for the variable group.

4. Under Variables, select + Add, and then enter a variable name and value to include in the group. If you want to encrypt and securely store the value, select the lock icon next to the variable.

5. Select + Add to add each new variable. When you finish adding variables, select Save.

   

You can now use this variable group in project pipelines.

Azure DevOps CLI

In Azure DevOps Services, you can create variable groups by using the Azure DevOps CLI.

To create a variable group, use the az pipelines variable-group create command.

For example, the following command creates a variable group named home-office-config, adds the variables app-location=home-office and app-name=contoso, and outputs results in YAML format.

az pipelines variable-group create --name home-office-config
                                   --variables app-location=home-office app-name=contoso
                                   --output yaml

Output:

authorized: false
description: null
id: 5
name: home-office-config
providerData: null
type: Vsts
variables:
  app-location:
    isSecret: null
    value: home-office
  app-name:
    isSecret: null
    value: contoso

Update variable groups

Azure Pipelines UI

You can update variable groups by using the Azure Pipelines user interface.

1. In your Azure DevOps project, select Pipelines > Library from the left menu.
2. On the Library page, select the variable group you want to update. You can also hover over the variable group listing, select the More options icon, and select Edit from the menu.
3. On the variable group page, change any of the properties, and then select Save.

Azure DevOps CLI

In Azure DevOps Services, you can update variable groups by using the Azure DevOps CLI.

List variable groups

To update a variable group or the variables within it by using the Azure DevOps CLI, you use the variable group group-id.

You can get the value of the variable group ID from the output of the variable group creation command, or use the az pipelines variable-group list command.

For example, the following command lists the first three project variable groups in ascending order and returns the results, including variable group ID, in table format.

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

Output:

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

Update a variable group

To update a variable group, use the az pipelines variable-group update command.

Note

You can't update a variable group of type AzureKeyVault using the Azure DevOps CLI.

For example, the following command updates the variable group with ID 4 to change the name and description, and outputs results in table format.

az pipelines variable-group update --group-id 4
                                   --name my-new-variables
                                   --description "New home office variables"
                                   --output table

Output:

ID    Name              Description               Is Authorized  Number of Variables
----  ----------------  ------------------------- -------------  -------------------
4     my-new-variables  New home office variables false          2

Show details for a variable group

You can use the az pipelines variable-group show command to show details for a variable group. For example, the following command shows details for the variable group with ID 4 and returns the results in YAML format.

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

Output:

authorized: false
description: Variables for my new app
id: 4
name: my-new-variables
providerData: null
type: Vsts
variables:
  app-location:
    isSecret: null
    value: home-office
  app-name:
    isSecret: null
    value: contoso

Delete a variable group

Azure Pipelines UI

You can delete variable groups in the Azure Pipelines user interface.

1. In your Azure DevOps project, select Pipelines > Library from the left menu.
2. On the Library page, hover over the variable group you want to delete and select the More options icon.
3. Select Delete from the menu, and then select Delete on the confirmation screen.

Azure DevOps CLI

In Azure DevOps Services, you can delete variable groups by using the Azure DevOps CLI.

To delete a variable group, use the az pipelines variable-group delete command. For example, the following command deletes the variable group with ID 1 and doesn't prompt for confirmation.

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

Manage variables in variable groups

Azure Pipelines UI

You can change, add, or delete variables in variable groups by using the Azure Pipelines user interface.

1. In your Azure DevOps project, select Pipelines > Library from the left menu.
2. On the Library page, select the variable group you want to update. You can also hover over the variable group listing, select the More options icon, and select Edit from the menu.
3. On the variable group page, you can:
   • Change any of the variable names or values.
   • Delete any of the variables by selecting the garbage can icon next to the variable name.
   • Change variables to secret or nonsecret by selecting the lock icon next to the variable value.
   • Add new variables by selecting + Add.
4. After making changes, select Save.

Azure DevOps CLI

In Azure DevOps Services, you can manage variables in variable groups by using the Azure DevOps CLI.

List variables in a variable group

To list the variables in a variable group, use the az pipelines variable-group variable list command. For example, the following command lists all the variables in the variable group with ID 4 and shows the result in table format.

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

Output:

Name            Is Secret    Value
--------------  -----------  -----------
app-location    False        home-office
app-name        False        contoso

Add variables to a variable group

To add a variable to a variable group, use the az pipelines variable-group variable create command.

For example, the following command creates a new variable named requires-login with a default value of true in the variable group with ID 4. The result is shown in table format.

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

Output:

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

Update variables in a variable group

To update variables in a variable group, use the az pipelines variable-group variable update command.

Note

You can't update variables in a variable group of type AzureKeyVault using the Azure DevOps CLI. You can update variables via the az keyvault commands.

For example, the following command updates the requires-login variable with the new value false in the variable group with ID 4, and shows the result in YAML format. The command specifies that the variable is a secret.

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

The output shows the value as null instead of false because it's a secret hidden value.

requires-login:
  isSecret: true
  value: null

Manage secret variables

To manage secret variables, use the az pipelines variable-group variable update command with the following parameters:

• secret: Set to true to indicate that the variable's value is kept secret.
• prompt-value: Set to true to update the value of a secret variable by using an environment variable or prompt via standard input.
• value: For secret variables, use the prompt-value parameter to be prompted to enter the value via standard input. For noninteractive consoles, you can pick up the environment variable prefixed with AZURE_DEVOPS_EXT_PIPELINE_VAR_. For example, you can input a variable named MySecret by using the environment variable AZURE_DEVOPS_EXT_PIPELINE_VAR_MySecret.

Delete variables from a variable group

To delete a variable from a variable group, use the az pipelines variable-group variable delete command. For example, the following command deletes the requires-login variable from the variable group with ID 4.

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

The command prompts for confirmation because that is the default. Use the --yes parameter to skip the confirmation prompt.

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

Use variable groups in pipelines

You can use variable groups in YAML or Classic pipelines. Changes that you make to a variable group are automatically available to all the definitions or stages the variable group is linked to.

YAML

If you only name the variable group in YAML pipelines, anyone who can push code to your repository could extract the contents of secrets in the variable group. Therefore, to use a variable group with YAML pipelines, you must authorize the pipeline to use the group. You can authorize a pipeline to use a variable group in the Azure Pipelines user interface or by using the Azure DevOps CLI.

Authorization via the Pipelines UI

You can authorize pipelines to use your variable groups by using the Azure Pipelines user interface.

1. In your Azure DevOps project, select Pipelines > Library from the left menu.
2. On the Library page, select the variable group you want to authorize.
3. On the variable group page, select the Pipeline permissions tab.
4. On the Pipeline permissions screen, select + and then select a pipeline to authorize. Or, select the More actions icon, select Open access, and select Open access again to confirm.

Selecting a pipeline authorizes that pipeline to use the variable group. To authorize another pipeline, select the + icon again. Selecting Open access authorizes all project pipelines to use the variable group. Open access might be a good option if you don't have any secrets in the group.

Another way to authorize a variable group is to select the pipeline, select Edit, and then queue a build manually. You see a resource authorization error and can then explicitly add the pipeline as an authorized user of the variable group.

Authorization via the Azure DevOps CLI

In Azure DevOps Services, you can authorize variable groups by using the Azure DevOps CLI.

To authorize all project pipelines to use the variable group, set the authorize parameter in the az pipelines variable-group create command to true. This open access might be a good option if you don't have any secrets in the group.

Link a variable group to a pipeline

Once you authorize a YAML pipeline to use a variable group, you can use variables within the group in the pipeline.

To use variables from a variable group, add a reference to the group name in your YAML pipeline file.

variables:
- group: my-variable-group

You can reference multiple variable groups in the same pipeline. If multiple variable groups include the variables with the same name, the last variable group that uses the variable in the file sets the variable's value. For more information about precedence of variables, see Expansion of variables.

You can also reference a variable group in a template. The following variables.yml template file references the variable group my-variable-group. The variable group includes a variable named myhello.

variables:
- group: my-variable-group

The YAML pipeline references the variables.yml template, and uses the variable $(myhello) from the variable group my-variable-group.

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

Use variables in a linked variable group

You access the variable values in a linked variable group the same way you access variables you define within the pipeline. For example, to access the value of a variable named customer in a variable group linked to the pipeline, you can use $(customer) in a task parameter or a script.

If you use both standalone variables and variable groups in your pipeline file, use the name-value syntax for the standalone variables.

variables:
- group: my-variable-group
- name: my-standalone-variable
  value: 'my-standalone-variable-value'

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

To use a runtime expression:

variables:
- group: my-variable-group
- name: my-passed-variable
  value: $[variables.myhello]
- script: echo $(my-passed-variable)

To use macro syntax:

variables:
- group: my-variable-group

steps:
- script: echo $(myhello)

You can't access secret variables, including encrypted variables and key vault variables, directly in scripts. You must pass these variables as arguments to a task. For more information, see Secret variables.

Classic

Use variable groups in Classic pipelines

Classic pipelines can use variable groups without separate authorization. To use a variable group:

1. Open your Classic pipeline.

2. Select Variables > Variable groups, and then select Link variable group.

   • In a build pipeline, you see a list of available groups. Select a variable group and select Link. All the variables in the group are available for use within the pipeline.

   • In a release pipeline, you also see a dropdown list of stages in the pipeline. Link the variable group to the pipeline itself, or to one or more specific stages of the release pipeline. If you link to one or more stages, the variables from the variable group are scoped to these stages and aren't accessible in the other stages of the release.

   

When you set a variable with the same name in multiple scopes, the following precedence is used, highest first:

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

For more information about precedence of variables, see Expansion of variables.

Note

Variables in different groups that are linked to a pipeline in the same scope (for example, job or stage) will collide and the result may be unpredictable. Ensure that you use different names for variables across all your variable groups.

Related articles

• Define variables
• Define custom variables
• Use secret and nonsecret variables in variable groups
• Use Azure Key Vault secrets in Azure Pipelines
• Add approvals and checks