Variable groups for builds and releases

Azure Pipelines | TFS 2018 | TFS 2017

Note

In Microsoft Team Foundation Server (TFS) 2018 and previous versions, build and release pipelines are called definitions, service connections are called service endpoints, stages are called environments, and jobs are called phases.

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.

  3. Decide if you want the variable group to be accessible for any pipeline by setting the Allow access to all pipelines option. This option allows pipelines defined in YAML, which are not automatically authorized for variable groups, to use this variable group. See Use a variable group

  4. If you want to link secrets from an Azure key vault as variables, see the following section of this topic.

  5. 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.

  6. 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

You can add a variable group by referencing it in your YAML file:

variables:
- group: my-variable-group

If you use both variables and variable groups, you'll have to use name/value syntax for the individual (non-grouped) variables:

variables:
- group: my-variable-group
- name: my-bare-variable
  value: 'value of my-bare-variable'

Next you must authorize the variable group (this is a security feature: if you only had to name the variable group in YAML, then anyone who can push code to your repository could extract the contents of secrets in the variable group). To do this, or if you encounter a resource authorization error in your build, use one of the following techniques:

  • If you want to authorize any pipeline to use the variable group, which may be a suitable option if the do not have any secrets in the group, go the Pipelines hub, open the Library page, choose Variable groups, select the variable group in question, and enable the setting Allow access to all pipelines.

  • If you want to authorize a variable group for a specific pipeline, open the pipeline by selecting Edit and queue a build manually. You will see a resource authorization error and a "Fix it" action on the error. Choose this action to explicitly add the pipeline as an authorized user of the variable group.

Note

If you added a variable group to a pipeline and did not get a resource authorization error in your build when you expected one, turn off the Allow access to all pipelines setting described above.

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