Manage variable groups

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.

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

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

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

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.

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

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

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

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

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

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

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.

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

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

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.

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

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

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

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

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

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

requires-login:
  isSecret: true
  value: null

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.

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.

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.

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.