You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: Learn best practices for protecting secrets in Azure Pipelines.
4
-
ms.date: 07/05/2024
2
+
title: Secrets in pipelines
3
+
description: Learn about best practices for protecting secrets in Azure Pipelines.
4
+
ms.date: 09/10/2025
5
5
monikerRange: '>= azure-devops-2020'
6
+
#customer intent: As an Azure Pipelines user, I want to understand best practices for using secrets in Azure Pipelines so I can limit and control access to secrets in pipelines.
This article provides best practices on protecting secrets in Azure Pipelines. A secret is anything that you want to tightly control access to, such as API keys, passwords, certificates, or cryptographic keys.
13
-
14
-
Azure Pipelines doesn't generate secret values. However, you might need to add a secret to a pipeline to store sensitive data like an API key. To learn more about setting secret variables, see [Set secret variables](../process/set-secret-variables.md).
14
+
This article provides best practices for protecting secrets in Azure Pipelines. A secret is anything that you want to tightly control access to, such as API keys, passwords, certificates, or cryptographic keys. Azure Pipelines doesn't generate secret values, but you might need to add secrets to pipelines to store sensitive data like API keys.
## Don't use secrets if another method is available
19
-
20
-
The best method to protect a secret isn't to have a secret in the first place. Check to see if your pipeline can use a different method than using a secret to perform a task.
18
+
## Use another method
21
19
22
-
***Use service connections:**
23
-
- When you're targeting Azure or other services, use service connections instead of managing secrets in variables.
24
-
- Service connections allow you to securely connect to external services without exposing sensitive information directly in your pipeline configuration.
25
-
- For more information, see [Manage service connections](../library/service-endpoints.md) and [Connect to Microsoft Azure with an Azure Resource Manager service connection](../library/connect-to-azure.md).
20
+
Secrets present inherent security risks, so it's best not to use them at all. Instead of managing secrets in variables or exposing them in your pipeline configuration, see if your pipeline can use one of these other methods to do a task.
26
21
27
-
-**Use managed identities:**
28
-
- Consider using managed identities instead of handling secrets directly.
29
-
- Managed identities allow your applications and services to authenticate with Azure services without requiring explicit credentials.
30
-
- You can [use managed identities to access other Azure services](/entra/identity/managed-identities-azure-resources/managed-identities-status).
22
+
- Set up [service connections](../library/service-endpoints.md) to securely connect to Azure or other services like GitHub or Docker. For more information, see [Connect to Azure with an Azure Resource Manager service connection](../library/connect-to-azure.md).
23
+
- Use [managed identities](/entra/identity/managed-identities-azure-resources/managed-identities-status) to let your applications and services authenticate with Azure services without using explicit credentials.
24
+
- Use the [Azure CLI task](/azure/devops/pipelines/tasks/reference/azure-cli-v2) with the `addSpnToEnvironment` option in your pipeline to access service principal details without explicitly passing secrets.
31
25
32
-
-**Azure CLI task:**
33
-
- If you're using the [Azure CLI task](/azure/devops/pipelines/tasks/reference/azure-cli-v2), in your pipeline, consider using the `addSpnToEnvironment` setting to access service principal details in script without explicitly passing secrets.
34
-
35
-
For more information, see [Use service principals & managed identities](../../integrate/get-started/authentication/service-principal-managed-identity.md)
26
+
For more information, see [Use service principals and managed identities](../../integrate/get-started/authentication/service-principal-managed-identity.md).
36
27
37
28
## Use secret variables
38
29
39
-
Never store sensitive values as plaintext in an Azure Pipelines **.yml** file.
40
-
41
-
Secret variables can be used for private information like passwords, IDs, and other identifying data that you wouldn't want exposed in a pipeline. We recommend that you [set secret variables](../process/set-secret-variables.md) with Azure Key Vault. You can also set secret variables in the UI or in a variable group. We don't recommend using a logging command to set a secret variable. When you set a secret with a logging command, anyone who can access your pipeline can also see the secret.
30
+
Never store sensitive values as plain text in an *azure-pipelines.yml* file. You can use secret variables for private information like passwords, IDs, and other identifying data you don't want exposed. Secret variables are encrypted, so you can use them in pipelines without exposing their values.
42
31
43
-
Secret variables are encrypted and can be used in pipelines without exposing their values. Although their values aren't exposed, never echo secrets as output and don't pass secrets on the command line. Instead, we suggest that you map your secrets into environment variables.
32
+
- It's best to securely manage secret variables in [Azure Key Vault](/azure/key-vault/). You can also set secret variables in the pipeline definition UI or in a variable group.
33
+
- Don't use a logging command to set a secret variable, because anyone who can access your pipeline can also see the secret.
34
+
- Never echo secrets as output, and don't pass secrets on the command line. Instead, it's best to map your secrets into environment variables.
35
+
- When you create a secret, follow [variable naming guidelines](../process/variables.md#variable-naming-restrictions), and make sure your secret name doesn't disclose sensitive information.
44
36
45
-
When you create a secret, follow [variable naming guidelines](../process/variables.md#variable-naming-restrictions) and make sure that your secret name doesn't disclose sensitive information.
37
+
To learn more about setting secrets in variables, see [Set secret variables](../process/set-secret-variables.md).
46
38
47
39
### Limit access to secret variables
48
40
49
-
To limit access to secrets in Azure DevOps, follow these best practices:
50
-
51
-
- Store your secrets in [Azure Key Vault](/azure/key-vault/). With Azure Key Vault, you can then use Azure's role-based access control model to limit access to a secret or group of secrets.
52
-
- Set secret variables in the UI for a pipeline. Secret variables set in the pipeline settings UI for a pipeline are scoped to the pipeline where they're set. So, you can have secrets that are only visible to users with access to that pipeline.
53
-
- Set secrets in a variable group. Variable groups follow the [library security model](../library/index.md#library-security). You can control who can define new items in a library, and who can use an existing item.
41
+
To limit access to secrets in Azure DevOps, follow one of these practices:
42
+
43
+
- Store your secrets in [Azure Key Vault](/azure/key-vault/general/overview). By using Azure Key Vault, you can use Azure role-based access control to limit access to a secret or group of secrets.
44
+
- Set secret variables in the pipeline UI. These variables are scoped to the pipeline where they're set, so are visible only to users of that pipeline.
45
+
- Set secrets in [variable groups](../library/variable-groups.md). Variable groups follow the [library security](../library/index.md#library-security) model, so you can control who can access or create items.
54
46
55
47
## Don't write secrets to logs
56
48
57
-
Azure Pipelines attempts to scrub secrets from logs wherever possible, but it's not foolproof. Avoid echoing secrets to the console, using them in command line parameters, or logging them to files. Be cautious when you use Azure CLI commands that output sensitive information. Use the [`None output format`](https://aka.ms/clisecrets), and if you need to retrieve a secret from an Azure CLI call, [`Use none output format and retrieve security information to a secret variable`](/cli/azure/format-output-azure-cli#use-none-and-retrieve-security-information-at-a-later-time).
49
+
Azure Pipelines attempts to scrub secrets from logs wherever possible, but isn't foolproof. Avoid echoing secrets to the console, using them in command line parameters, or logging them to files.
50
+
51
+
Be cautious when you use Azure CLI commands that output sensitive information. Use the [None output format](https://aka.ms/clisecrets), and if you need to retrieve a secret from an Azure CLI call, [retrieve security information from a secret variable](/cli/azure/format-output-azure-cli#retrieve-security-information-at-a-later-time).
58
52
59
53
## Don't use structured data as secrets
60
54
61
-
Avoid using structured data formats like JSON, XML, or YAML, to encapsulate secret values, including control characters such as carriage return, `\r`, and line feed,`\n`. Instead, create individual secrets for each sensitive value. This approach ensures better redaction accuracy and minimizes the risk of exposing sensitive data inadvertently.
55
+
Avoid using structured data formats like JSON, XML, or YAML to encapsulate secret values, including control characters such as carriage return `\r` and line feed `\n`. Instead, create individual secrets for each sensitive value. This approach ensures better redaction accuracy and minimizes the risk of inadvertently exposing sensitive data.
56
+
57
+
## Audit secret use
62
58
63
-
## Audit how secrets are handled
59
+
To audit how your pipelines use secrets, follow these best practices:
64
60
65
-
To audit how secrets are used in Azure Pipelines, follow these best practices:
61
+
- Examine the source code of the repository that hosts the pipeline. To ensure secrets are handled correctly, check all tasks the pipeline uses. Verify that secrets aren't inadvertently sent to unintended hosts or explicitly printed to log output.
66
62
67
-
-**Review source code:** Examine the source code of the repository hosting the pipeline. To ensure secrets get handled correctly, check any tasks used in the pipeline. For instance, verify that secrets aren't inadvertently sent to unintended hosts or explicitly printed to log output.
68
-
-**Inspect run logs:** After testing valid and invalid inputs, view the run logs for your pipeline. Ensure that secrets are properly redacted and not exposed. Sometimes, errors in commands or tools might inadvertently leak secrets into error logs. While Azure Pipelines attempts to scrub secrets from logs, manual review is still essential.
63
+
- After testing valid and invalid inputs, view the run logs for your pipeline. Ensure that secrets are properly redacted and not exposed. Sometimes, errors in commands or tools might inadvertently leak secrets into error logs. While Azure Pipelines attempts to scrub secrets from logs, manual review is still essential.
69
64
70
65
## Audit and rotate secrets
71
66
72
67
To audit and rotate secrets, follow these best practices:
73
68
74
-
-**Review registered secrets:** Periodically assess the secrets registered in your pipelines. Confirm that they're still necessary, and remove any that are no longer needed, which helps reduce clutter and potential security risks.
75
-
-**Rotate secrets:** Regularly rotate secrets to minimize the window of time during which a compromised secret could be exploited. By changing secrets periodically, you enhance security.
76
-
-**[Secret variables](../process/set-secret-variables.md):** Use secret variables to securely store sensitive information like API keys, passwords, or other credentials within your pipeline.
77
-
-**[Azure Key Vault](/azure/key-vault/general/overview):** Use Azure Key Vault to store and manage secrets securely.
78
-
-**[Service connections](../library/service-endpoints.md):** These service connections allow your pipeline to connect to external services (for example, Azure, GitHub, Docker Hub). Ensure proper configuration and secure handling of service connection secrets.
79
-
-[**Personal access tokens (PATs)**](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md): Keep PAT duration short and choose the minimal permissions needed during creation.
69
+
- Periodically review the secrets registered in your pipelines. Confirm that they're still necessary and remove any that are no longer needed. This practice helps reduce clutter and potential security risks.
70
+
- Ensure proper configuration and secure handling of service connection secrets.
71
+
- Keep [personal access token (PAT)](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) duration short and choose the minimal permissions needed.
72
+
- Regularly rotate secrets to minimize the amount of time that a compromised secret could be exploited. Changing secrets periodically enhances security.
80
73
81
74
## Use YAML templates
82
75
83
76
Instead of including inline scripts with secret parameters directly in your pipeline YAML, use [templates](templates.md). This approach enhances security by abstracting sensitive information away from the main pipeline.
84
77
85
-
To implement this approach, create a separate YAML file for your script and then store that script in a separate, secure repository. You can then reference the template and pass a secret variable in your YAML as a parameter. The secure variable should come from Azure Key Vault, a variable group, or the pipeline UI. For more information on using templates, see the [Template usage reference](../process/templates.md).
78
+
To implement this approach, create a separate YAML file for your script and store that script in a separate, secure repository. You can then reference the template and pass a secret variable from Azure Key Vault, a variable group, or the pipeline UI in your YAML as a parameter. For more information about using templates, see the [Template usage reference](../process/templates.md).
86
79
87
80
## Limit secrets with branch policies and variable group permissions
88
81
89
-
To make sure that secrets are tied to the `main` branch and not accessible to random branches, you can use a combination of variable group permissions, conditional job insertion, and branch policies.
82
+
To ensure that secrets are accessible only to a certain repository branch, you can use a combination of branch policies, variable group permissions, and conditional job insertion.
90
83
91
-
With branch policies, you can enforce [build validation policies](../../repos/git/branch-policies.md#build-validation) that only allow builds from the main branch. Then, you can use [variable group permissions](../library/variable-groups.md) to make sure that only authorized pipelines have access to the secrets stored in your variable group. Last, you can use a condition in your pipeline to make sure that the variable group can only be referenced by a push to the `main` branch.
84
+
Enforce [build validation policies](../../repos/git/branch-policies.md#build-validation) that allow builds only from a certain branch. Thenuse [variable group permissions](../library/variable-groups.md) to ensure that only authorized pipelines can access the secrets stored in your variable group. Finally, use a condition in your pipeline to ensure that only a push to the designated branch can reference the variable group.
92
85
93
86
```yaml
94
87
jobs:
@@ -103,12 +96,8 @@ jobs:
103
96
- group: your-variable-group-name
104
97
```
105
98
106
-
## Next steps
107
-
108
-
> [!div class="nextstepaction"]
109
-
> [Best practices for protecting Azure secrets](/azure/security/fundamentals/secrets-best-practices)
110
-
111
-
## Related articles
99
+
## Related content
112
100
113
-
- [Key and secret management considerations in Azure](/azure/well-architected/security/design-storage-keys)
101
+
- [Best practices for protecting secrets](/azure/security/fundamentals/secrets-best-practices)
102
+
- [Architecture strategies for protecting application secrets](/azure/well-architected/security/design-storage-keys)
0 commit comments