Set secret variables

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Secret variables are encrypted variables that you can use in pipelines without exposing their value. Secret variables can be used for private information like passwords, IDs, and other identifying data that you wouldn't want exposed in a pipeline. Secret variables are encrypted at rest with a 2048-bit RSA key and are available on the agent for tasks and scripts to use.

The recommended ways to set secret variables are in the UI, in a variable group, and in a variable group from Azure Key Vault. You can also set secret variables in a script with a logging command but this isn't recommended since anyone who can access your pipeline can also see the secret.

Secret variables set in the pipeline settings UI for a pipeline are scoped to the pipeline where they're set. You can use variable groups to share secret variables across pipelines.

Secret variable in the UI

You can set secret variables in the pipeline editor when you're editing an individual pipeline. You'll encrypt and make a pipeline variable secret by selecting the lock icon.

You set secret variables the same way for YAML and Classic.

To set secrets in the web interface, follow these steps:

1. Go to the Pipelines page, select the appropriate pipeline, and then select Edit.
2. Locate the Variables for this pipeline.
3. Add or update the variable.
4. Select the option to Keep this value secret to store the variable in an encrypted manner.
5. Save the pipeline.

Secret variables are encrypted at rest with a 2048-bit RSA key. Secrets are available on the agent for tasks and scripts to use. Be careful about who has access to alter your pipeline.

Important

We make an effort to mask secrets from appearing in Azure Pipelines output, but you still need to take precautions. Never echo secrets as output. Some operating systems log command line arguments. Never pass secrets on the command line. Instead, we suggest that you map your secrets into environment variables.

We never mask substrings of secrets. If, for example, "abc123" is set as a secret, "abc" isn't masked from the logs. This is to avoid masking secrets at too granular of a level, making the logs unreadable. For this reason, secrets should not contain structured data. If, for example, "{ "foo": "bar" }" is set as a secret, "bar" isn't masked from the logs.

Unlike a normal variable, they are not automatically decrypted into environment variables for scripts. You need to explicitly map secret variables.

Use a secret variable in the UI

YAML

You'll need to map secret variable as environment variables to reference them in YAML pipelines. In this example, there are two secret variables defined in the UI, SecretOne and SecretTwo. The value of SecretOne is foo and the value of SecretTwo is bar.

steps:
- powershell: |
      Write-Host "My first secret variable is $env:FOO_ONE"
      $env:FOO_ONE -eq "foo"
  env:
    FOO_ONE: $(SecretOne)
- bash: |
    echo "My second secret variable: $FOO_TWO"
    if [ "$FOO_TWO" = "bar" ]; then
        echo "Strings are equal."
    else
        echo "Strings are not equal."
    fi
  env:
    FOO_TWO: $(SecretTwo) 

The pipeline outputs:

My first secret variable is ***
True
My second secret variable: ***
Strings are equal.

Note

Azure Pipelines makes an effort to mask secrets when emitting data to pipeline logs, so you may see additional variables and data masked in output and logs that are not set as secrets.

For a more detailed example, see Define variables.

Classic

Unlike a normal variable, secret aren't automatically decrypted into environment variables for scripts. You need to explicitly map secret variables.

In this example, the variable mySecret is set on the Variables tab. The value of mySecret is foo.

Each task that needs to use the secret as an environment variable does remapping. If you want to use the secret variable mySecret in a script, use the Environment Variables section of the task. Set the environment variable name to FOO_ONE, and set the value to $(mySecret).

The script outputs True.

Set a secret variable in a variable group

You can add secrets to a variable group or link secrets from an existing Azure Key Vault.

Create new variable groups

1. Select Pipelines > Library > + Variable group.

   

2. Enter a name and description for the group.

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

4. Enter the name and value for each variable to include in the group, choosing + Add for each one.

5. To make your variable secure, 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.

Link secrets from an Azure key vault

You can create a variable group that links to an existing Azure key vault and map selected Key Vault secrets to the variable group. Only the secret names are mapped to the variable group, not the secret values. Pipeline runs that link to the variable group fetch the latest secret values from the vault.

Any changes made to existing secrets in the key vault are automatically available to all the pipelines that use the variable group. However, if secrets are added to or deleted from the vault, the associated variable groups don't automatically update. You must explicitly update the secrets to include in the variable group.

Although Key Vault supports storing and managing cryptographic keys and certificates in Azure, Azure Pipelines variable group integration only supports mapping key vault secrets. Cryptographic keys and certificates aren't supported.

Note

Key vaults that use Azure role-based access control (Azure RBAC) aren't supported.

Prerequisites

• An Azure key vault that contains your secrets. You can create a key vault by using the Azure portal.
• An Azure service connection for your project.

Create the variable group

1. In your Azure DevOps project, select Pipelines > Library > + Variable group.
2. On the Variable groups page, enter a name and optional description for the variable group.
3. Enable the Link secrets from an Azure key vault as variables toggle.
4. Select your Azure subscription endpoint and key vault name.
5. Enable Azure DevOps to access the key vault by selecting Authorize next to the vault name.
6. On the Choose secrets screen, select specific secrets from your vault for mapping to this variable group, and then select OK.
7. Select Save to save the secret variable group.

Note

Your Azure service connection must have at least Get and List permissions on the key vault, which you can authorize in the preceding steps. You can also provide these permissions from the Azure portal by following these steps:

1. Open Settings for the key vault, and then choose Access configuration > Go to access policies.
2. On the Access policies page, if your Azure Pipelines project isn't listed under Applications with at least Get and List permissions, select Create.
3. Under Secret permissions, select Get and List, and then select Next.
4. Select your service principal, and then select Next.
5. Select Next again, review the settings, and then select Create.

Use the Azure Key Vault task

You can use the Azure Key Vault task to include secrets in your pipeline. This task allows the pipeline to connect to your Azure Key Vault and retrieve secrets to use as pipeline variables.

1. In the pipeline editor, select Show assistant to expand the assistant panel.

2. Search for vault and select the Azure Key Vault task.

   

The Make secrets available to whole job option isn't currently supported in Azure DevOps Server 2019 and 2020.

To learn more about the Azure Key Vault task, see Use Azure Key Vault secrets in Azure Pipelines.

Set secret variable in a script with logging commands

You can use the task.setvariable logging command to set variables in PowerShell and Bash scripts. This is the least secure way to work with secret variables but can be useful for debugging. The recommended ways to set secret variables are in the UI, in a variable group, and in a variable group from Azure Key Vault.

To set a variable as a script with a logging command, you'll need to pass the issecret flag.

When issecret is set to true, the value of the variable will be saved as secret and masked out from logs.

Note

Azure Pipelines makes an effort to mask secrets when emitting data to pipeline logs, so you may see additional variables and data masked in output and logs that are not set as secrets.

Bash

Set the secret variable mySecretVal.

- bash: |
    echo "##vso[task.setvariable variable=mySecretVal;issecret=true]secretvalue"

Get the secret variable mySecretVal.

- bash: |
    echo "##vso[task.setvariable variable=mySecretVal;issecret=true]secretvalue"
- bash: |
    echo $(mySecretVal)

Secret variable output in bash.

PowerShell

Set the secret variable mySecretVal.

- powershell: |
    Write-Host "##vso[task.setvariable variable=mySecretVal;issecret=true]secretvalue"

Get the secret variable mySecretVal.

- powershell: |
    Write-Host "##vso[task.setvariable variable=mySecretVal;issecret=true]secretvalue"
- powershell: |
    Write-Host $(mySecretVal)

Output of PowerShell variable.

Learn more about setting and using variables in scripts.

Related articles

• Define variables
• Use variables in a variable group
• Use predefined variables
• Set variables in scripts