Redigeeri

Jagamisviis:

Manage variable groups

  • Artikkel

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.

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 secrets from an Azure key vault.

You can create a variable group in the Azure Pipelines user interface.

Prerequisites

An Azure DevOps organization and project where you have permissions to create pipelines and variables.

Create the variable group

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

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

    Screenshot of the Library screen and Add variable group button.

  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.

    Screenshot of configuring and saving a variable group.

You can now use this variable group in project pipelines.

You can create a variable group that links to an existing Azure key vault and map selected Key Vault secrets to the variable group. Only the secret names are mapped to the variable group, not the secret values. Pipeline runs that link to the variable group fetch the latest secret values from the vault.

Any changes made to existing secrets in the key vault are automatically available to all the pipelines that use the variable group. However, if secrets are added to or deleted from the vault, the associated variable groups don't automatically update. You must explicitly update the secrets to include in the variable group.

Although Key Vault supports storing and managing cryptographic keys and certificates in Azure, Azure Pipelines variable group integration only supports mapping key vault secrets. Cryptographic keys and certificates aren't supported.

Note

Key vaults that use Azure role-based access control (Azure RBAC) aren't supported.

Prerequisites

Create the variable group

  1. In your Azure DevOps project, select Pipelines > Library > + Variable group.
  2. On the Variable groups page, enter a name and optional description for the variable group.
  3. Enable the Link secrets from an Azure key vault as variables toggle.
  4. Select your Azure subscription endpoint and key vault name.
  5. Enable Azure DevOps to access the key vault by selecting Authorize next to the vault name.
  6. On the Choose secrets screen, select specific secrets from your vault for mapping to this variable group, and then select OK.
  7. Select Save to save the secret variable group.

Screenshot of variable group with Azure key vault integration.

Note

Your Azure service connection must have at least Get and List permissions on the key vault, which you can authorize in the preceding steps. You can also provide these permissions from the Azure portal by following these steps:

  1. Open Settings for the key vault, and then choose Access configuration > Go to access policies.
  2. On the Access policies page, if your Azure Pipelines project isn't listed under Applications with at least Get and List permissions, select Create.
  3. Under Secret permissions, select Get and List, and then select Next.
  4. Select your service principal, and then select Next.
  5. Select Next again, review the settings, and then select Create.

For more information, see Use Azure Key Vault secrets.

Update variable groups

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.

Delete a variable group

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.

Manage variables in variable groups

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.

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.

Use variable groups in YAML pipelines

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

Authorize the YAML pipeline to use the variable group

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. Classic pipelines can use variable groups without separate authorization.

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.

Use the variable group in the YAML pipeline

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

variables:
- group: my-variable-group

You can reference multiple variable groups in the same pipeline. If multiple variable groups include the same variable, 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 variable group variables in YAML pipelines

You access the variable values in a linked variable group the same way as 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.

  3. In a build pipeline, you see a list of available groups. Link a variable group to the pipeline. 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.

    Screenshot that shows linking a variable group.

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.