ערוך

שתף באמצעות


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.
  • An Azure DevOps Server collection 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.

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.

  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.

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.

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.

Azure DevOps CLI commands aren't supported for Azure DevOps Server.

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.

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.