Variable groups for builds and releases

Azure Pipelines | TFS 2018 | TFS 2017

Note

Build and release pipelines are called definitions in Microsoft Team Foundation Server (TFS) 2018 and in older versions. Service connections are called service endpoints in TFS 2018 and in older versions.

Use a variable group to store values that you want to make available across multiple build and release pipelines. Variable groups are defined and managed in the Library tab of the Pipelines hub.

Note

Variable groups can be used in a build pipeline in only Azure DevOps and TFS 2018. They cannot be used in a build pipeline in earlier versions of TFS.

Create a variable group

  1. Open the Library tab to see a list of existing variable groups for your project. Choose + Variable group.

  2. Enter a name and description for the group. Then enter the name and value for each variable you want to include in the group, choosing + Add for each one. If you want to encrypt and securely store the value, choose the "lock" icon at the end of the row. When you're finished adding variables, choose Save.

    Saving a variable group

Variable groups follow the library security model.

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

    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. You can enable Azure Pipelines to set these permissions by choosing Authorize next to the vault name. Alternatively, you can set the permissions manually in the Azure portal:

    • Open the Settings blade for the vault, choose Access policies, then Add new.
    • In the Add access policy blade, choose Select principal and select the service principal for your client account.
    • In the Add access policy blade, choose Secret permissions and ensure that Get and List are checked (ticked).
    • Choose OK to save the changes.

  3. In the Variable groups page, choose + Add to select specific secrets from your vault that will be mapped to this variable group.

Secrets management notes

  • Only the secret names are mapped to the variable group, not the secret values. The latest version of the value of each secret is fetched from the vault and used in the pipeline linked to the variable group during the build or release.

  • Any changes made to existing secrets in the key vault, such as a change in the value of a secret, will be made available automatically to all the definitions in which the variable group is used.

  • When new secrets are added to the vault, or a secret is deleted from the vault, the associated variable groups are not updated automatically. The secrets included in the variable group must be explicitly updated in order for the definitions using the variable group to execute 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 are not yet supported.

Use a variable group

To use a variable group, reference it in your variables mapping:

variables:
- group: my-variable-group

YAML builds are not yet available on TFS.

You access the value of the variables in a linked variable group in exactly 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. However, secret variables (encrypted variables and key vault variables) cannot be accessed directly in scripts - instead they must be passed as arguments to a task.

Note: At present, variables in different groups that are linked to a pipeline in the same scope (such as a release or stage scope) will collide and the result may be unpredictable. Ensure that you use different names for variables across all your variable groups.

Any changes made centrally to a variable group, such as a change in the value of a variable or the addition of new variables, will automatically be made available to all the definitions or stages to which the variable group is linked.

Variable groups in a build or release

The recommended use of linking a variable group to a pipeline is when you want to centrally control values for variables that are used across multiple instances or releases of the pipeline.

  • When a new instance of a build or release is created from a pipeline definition, the values of the variables from the linked variable group are copied to the build or release.
  • To override the values of variables in the variable group you must create a variable with the same name within the build or release pipeline. A variable in the pipeline overrides a variable with the same name in the variable group.
  • To override the values of variables in the variable group for only a specific release, you can edit the release and add new variables for just that release by using the same variable name as defined in the variable group.
  • To override the values between releases from the pipeline, use variables with same name at queue time:
    • When you create the release, you can choose the variables you would like to set.
    • The value you set for a variable when the release is created is used only for that release.
    • This helps to avoid the multiple steps of create in draft, update the variables in draft, and trigger the release with the variable.

Help and support