Add & use variable groups

TFS 2017

Variable groups store values and secrets that you might want to be passed into a YAML pipeline or make available across multiple pipelines. You can share and use variables groups in multiple pipelines in the same project.

Variables groups are protected resources. You can add approvals and checks to these variables and set pipeline permissions.

Note

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

Note

Variable groups can be used in a build pipeline only Azure DevOps and TFS 2018.

Create a variable group

YAML

You can't create variable groups in YAML, but they can be used as described in Use a variable group.

Classic

1. Sign in to your organization (https://dev.azure.com/{yourorganization}) and select your project.

2. Select Pipelines > Library > + Variable group.

   

3. Enter a name and description for the group.

4. Optional: Move the toggle to link secrets from an Azure key vault as variables. For more information, see Use Azure Key Vault secrets.

5. Enter the name and value for each variable 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, select Save.

   

Variable groups follow the library security model.

Use a variable group

YAML

YAML builds aren't available on TFS-2017.

Classic

To use a variable group, open your pipeline. Select Variables > Variable groups, and then choose Link variable group. In a build pipeline, you see a list of available groups. In a release pipeline, for example, you also see a drop-down list of stages in the pipeline. Link the variable group to one or more of these stages in the pipeline.

• build pipeline: The variable group gets linked to the pipeline. All the variables in the group are available for use within the pipeline.
• release pipeline: Link a variable group to the pipeline itself, or to a specific stage of the release pipeline.
  • If you link to a release pipeline, all the variables in the group are available for use in the pipeline, in all stages.
  • If you link to one or more stages in a release pipeline, the variables from the variable group get scoped to these stages and aren't accessible in the other stages of the same release.

Note

Linking a variable group to a specific stage is available only on Azure Pipelines and on TFS 2018 Update 2 and later.

Access the variable values in a linked variable group 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. But, you can't access secret variables (encrypted variables and key vault variables) directly in scripts - instead, they must be passed as arguments to a task. For more information, see secrets

Changes that you make to a variable group are automatically available to all the definitions or stages to which the variable group gets linked.

Link secrets from an Azure key vault

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

   

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. Enable Azure Pipelines to set these permissions by choosing Authorize next to the vault name. Or, set the permissions manually in the Azure portal:

   1. Open Settings for the vault, and then choose Access policies > Add new.
   2. Select Select principal and then choose the service principal for your client account.
   3. Select Secret permissions and ensure that Get and List have check marks.
   4. Select OK to save the changes.

3. On the Variable groups page, select + Add to select specific secrets from your vault for mapping to this variable group.

Manage secrets

See the following list of helpful tips for managing secrets.

• Only the secret names get mapped to the variable group, not the secret values. The latest secret value, fetched from the vault, is used in the pipeline run that's linked to the variable group.

• Any change made to existing secrets in the key vault is automatically available to all the pipelines the variable group's used in.

• When new secrets get added to or deleted from the vault, the associated variable groups aren't automatically updated. The secrets included in the variable group must be explicitly updated so the pipelines that are using the variable group get executed 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 aren't supported.

Expand variables in a group

YAML

YAML isn't supported in TFS 2017.

Classic

When you set a variable with the same name in multiple scopes, the following precedence is used (highest precedence first).

1. Variable set at queue time
2. Variable set in the pipeline
3. Variable set in the variable group

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.

Related articles

• Use Azure Key Vault secrets in Azure Pipelines
• Define variables
• Use secret and nonsecret variables in variable groups
• Add approvals and checks