Variable groups

VSTS | TFS 2018 | TFS 2017

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

Create a variable group

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

    Creating a 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 endpoint has at least Get and List management permissions on the vault for secrets. You can enable VSTS 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 definition 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, they are not made available automatically to all the definitions. New secrets must be explicitly added to the variable group in order to make them available to definitions in which the variable group is used.

  • Azure Key Vault supports storing and managing cryptographic keys and secrets in Azure. Currently, VSTS 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, open the definition, select the Variables tab, select Variable groups, and then choose Link variable group.

Linking a variable group

You can link a variable group to a release definition, or to a specific environment in a release definition. When you link to a release definition, all the variables in the group are available for use in all environments of that definition. When you link to an environment, the variables from the variable group scoped to that environment and are not accessible in the other environments of the same release.

You access the value of the variables in a linked variable group in exactly the same way as variables you define within the definition itself. For example, to access the value of a variable named customer in a variable group linked to the definition, 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.

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 environments to which the variable group is linked.

Help and support