years
2021, 2026

lastupdated

2026-04-09

keywords

tool integrations, IBM Cloud Public, IBM Secrets Manager

subcollection

ContinuousDelivery

Configuring {{site.data.keyword.secrets-manager_short}}

{: #secretsmanager}

{{site.data.keyword.contdelivery_short}} will be discontinued in the following regions on 10 April 2026: eu-es and jp-osa. This discontinuation also applies to any features provided within the service, including Code Risk Analyzer and {{site.data.keyword.DRA_short}}. Learn more {: important}

{{site.data.keyword.contdelivery_short}} will be discontinued in the following regions on 12 February 2027: au-syd, ca-mon, ca-tor, us-east. Code Risk Analyzer and {{site.data.keyword.DRA_short}} will also be deprecated in all regions on that date. However, if a region has no active usage of these features, the features in that region may be discontinued earlier and stop accepting new instances. Learn more {: important}

{{site.data.keyword.secrets-manager_full}} helps you to securely store and apply secrets for apps across {{site.data.keyword.cloud_notm}} services. {: shortdesc}

A secret is anything that provides access to sensitive information, such as an API key. You can use the {{site.data.keyword.secrets-manager_short}} tool integration to access secrets, wherever they are required in the toolchain workflow.

Before you configure a {{site.data.keyword.secrets-manager_short}} tool integration, make sure that you provision an instance of the {{site.data.keyword.secrets-manager_short}} service. {: important}

You can configure the {{site.data.keyword.secrets-manager_short}} tool integration to identify secrets by name or by Cloud Resource Name (CRN).

Identifying secrets by name

{: #identify_secrets_by_name}

When you configure the {{site.data.keyword.secrets-manager_short}} tool integration to identify secrets by name, your toolchain can access the following secret types:

Identity and Access Management (IAM) credentials secrets.
Arbitrary secrets that are stored in the {{site.data.keyword.secrets-manager_short}}.
Key-value secrets.

References to secrets by name are currently not able to resolve a secret that includes the period character in the secret name because this character is used to delimit each section of the canonical path. {: note}

For more information about IAM credentials secrets, Arbitrary secrets and Key-value secrets in {{site.data.keyword.secrets-manager_short}}, see Working with secrets of different types.

Configure {{site.data.keyword.secrets-manager_short}} to securely manage secrets that are part of your toolchain:

If you are configuring this tool integration as you are creating the toolchain, in the Configurable Integrations section, click {{site.data.keyword.secrets-manager_short}}. If {{site.data.keyword.secrets-manager_short}} is defined as an optional tool integration, it is located under More Tools. Choose to identify this instance by the service instance name. To create an authorization between the toolchain and the {{site.data.keyword.secrets-manager_short}} service instance select the Create an authorization for this toolchain option from the Authorization type dropdown. This grants the toolchain access to the secret material stored in the {{site.data.keyword.secrets-manager_short}} service instance.
If you have a toolchain and are adding this tool integration to it, from the {{site.data.keyword.cloud_notm}} console, click the Menu icon > Platform Automation > Toolchains. On the Toolchains page, click the toolchain to open its Overview page. Alternatively, on your app's Overview page, on the {{site.data.keyword.contdelivery_short}} card, click View toolchain. Then, click Overview.

a. Click Add tool.

b. In the Tool Integrations section, click {{site.data.keyword.secrets-manager_short}}.
Specify a name for this instance of the {{site.data.keyword.secrets-manager_short}} tool integration to use in your toolchain. The name that you specify is used in the UI tools that select {{site.data.keyword.secrets-manager_short}} secrets. It is also used as part of the reference that resolves the secret values when the toolchain runs. This instance name is also displayed on the {{site.data.keyword.secrets-manager_short}} tool integration tile within the toolchain workspace.
Choose to identify this instance by the service instance name.
Review the default values for Region and Resource-Group and update, if required.
Select the instance of the {{site.data.keyword.secrets-manager_short}} service that you want to use.
To create an authorization between the toolchain and the {{site.data.keyword.secrets-manager_short}} service instance click the Create Authorization button. This grants the toolchain access to the secret material stored in the {{site.data.keyword.secrets-manager_short}} service instance.
Click Create Integration.

Applying secrets

{: #secretsmanager_apply_secrets_name}

After your {{site.data.keyword.secrets-manager_short}} tool integration is configured, you can use it to apply secrets anywhere that they are needed by the toolchain. This tool integration and the Secrets dialog box support both the Arbitrary and the IAM credentials secret types.

You can use Arbitrary secrets to store any predefined secret value, or to store dynamically minted {{site.data.keyword.cloud_notm}} API keys by using the Secrets dialog box. You must create IAM credentials secrets directly within your {{site.data.keyword.secrets-manager_short}} service instance. After you create these secrets, you can select IAM credentials secrets to use them within your toolchain by using the Secrets dialog box on any secure field. The Secrets dialog box displays both the Arbitrary and the IAM credentials secret types, with the secret type appended to the secret name in brackets.

Using arbitrary secrets that are stored in {{site.data.keyword.secrets-manager_short}}

{: #arbitrary_secrets}

You must save third-party secrets, such as a Slack webhook or an Artifactory API token, in {{site.data.keyword.secrets-manager_short}} before you create a new toolchain. You can mint and store IBM-managed secrets, such as {{site.data.keyword.cloud_notm}} API keys in {{site.data.keyword.secrets-manager_short}}, as Arbitrary secret types while you work with your toolchain by using the Secrets dialog. However, you must mint IAM credentials secrets directly in {{site.data.keyword.secrets-manager_short}} before you can select these types of secrets within your toolchain by using the Secrets dialog box.

The following example applies an Arbitrary secret type that is stored in {{site.data.keyword.secrets-manager_short}} to an {{site.data.keyword.cloud_notm}} API key that is required by the {{site.data.keyword.deliverypipeline}} tool integration. You can follow the same steps to apply secrets to any of the {{site.data.keyword.contdelivery_short}} tool integrations that require secret values.

Click the key icon to retrieve secrets from secure stores such as {{site.data.keyword.secrets-manager_short}} for the {{site.data.keyword.cloud_notm}} API key.
In the Provider field, specify the provider and the name of the {{site.data.keyword.secrets-manager_short}} tool integration that you use to manage your toolchain secrets. For example, to use the {{site.data.keyword.secrets-manager_short}} tool integration, select Secrets Manager: ibm-secrets-manager-1. You can use other providers to manage your toolchain secrets, such as HashiCorp Vault and Key Protect.
Select a secret group and a secret name and click OK to apply the stored secret to the field that is associated with it.

{: caption="Secret reference to a vault" caption-side="bottom"}

The name of the secret that you select appears in capsule form. You cannot edit the secret name inline, but you can click to delete the name. You can also replace the existing secret name by selecting the secret name again. If you manually type or paste a secret name into the Secrets field, it is displayed in a different format:

{: caption="Secret value" caption-side="bottom"}

The format that the secret is displayed in indicates whether the value references a secret that is stored in a backend vault or a secret that is stored in your toolchain. By using references to secrets that are managed by secret providers such as {{site.data.keyword.secrets-manager_short}}, your secret values are centralized and stored securely in a single location. This approach resolves secrets sprawl and proliferation, and means that you can update secrets without updating your toolchain. When you use secret references, the actual secret value is resolved when the toolchain runs by dynamically retrieving it from {{site.data.keyword.secrets-manager_short}}. This approach is useful when you must rotate the value of your toolchain secrets periodically.

Using IAM credentials secrets

{: #iam_secrets}

The IAM credentials secret type is fully integrated with IAM. {{site.data.keyword.secrets-manager_short}} auto-manages dynamic service IDs and API keys that are associated with an IAM credentials secret. {{site.data.keyword.contdelivery_short}} and {{site.data.keyword.secrets-manager_short}} service APIs engage to resolve authorized IAM Credentials secret references in {{site.data.keyword.contdelivery_short}} toolchains and pipeline workloads.

When you create an IAM credentials secret in {{site.data.keyword.secrets-manager_short}}, make sure that you select the Reuse IAM credentials until lease expires checkbox. Also, specify a lease duration with a minimum of 12 hours when you use public worker agents to run your pipeline. If you use private worker agents, make sure that you set a minimum lease duration to the forced cancellation duration for a pipeline. It is recommended that you confirm these settings with your account administrator. By setting the reuse option and an appropriate lease duration, you can make sure that the dynamically managed IAM credentials service ID API key persists during your pipeline runs. {: important}

{: caption="IAM credentials lease duration and reuse API key" caption-side="bottom"}

By running the Rotate action on IAM credentials from the {{site.data.keyword.secrets-manager_short}} dashboard, you can maintain the compliance posture requirements for API Key rotations that are used by your {{site.data.keyword.contdelivery_short}} pipelines. {{site.data.keyword.secrets-manager_short}} works with IAM to generate a new API Key for an IAM credentials secret and manages the versioning of the secret.

The IAM credentials secret type also helps to provide continuity of service during and after secret rotation:

New {{site.data.keyword.contdelivery_short}} pipeline workloads use the newly rotated API Key until its lease duration expires.
Existing {{site.data.keyword.contdelivery_short}} pipeline workloads that are running with the API Key that was issued before rotation can continue to run with the previous version until the lease duration of the previous version expires.

{: caption="IAM credentials secret rotation" caption-side="bottom"}

For more information about the IAM credentials secret type in {{site.data.keyword.secrets-manager_short}}, see Creating IAM credentials.

Using key-value secrets

{: #key_value_secrets}

You can select the key-value secrets to use in your toolchain by selecting an individual key from the key-value secret in the Secrets dialog. Alternatively, you can select the secret in its entirety.

Click the key icon to retrieve secrets from secure stores such as {{site.data.keyword.secrets-manager_short}} for the {{site.data.keyword.cloud_notm}} API key.
In the Provider field, specify the provider and the name of the {{site.data.keyword.secrets-manager_short}} tool integration that you use to manage your toolchain secrets. For example, to use the {{site.data.keyword.secrets-manager_short}} tool integration, select Secrets Manager: ibm-secrets-manager-1. You can use other providers to manage your toolchain secrets, such as HashiCorp Vault and Key Protect.
Select a secret group and a secret name to apply the stored secret to the field that is associated with it. Optional: select a secret key. Click OK. The name of the secret that you select appears in capsule form. You cannot edit the secret name inline, but you can click to delete the name. You can also replace the existing secret name by selecting the secret name again. If you manually type or paste a secret name into the Secrets field, it is displayed in a different format.

Adding a {{site.data.keyword.secrets-manager_short}} tool integration to your toolchain template

{: #secretsmanager_add_toolchain_template}

You can add a {{site.data.keyword.secrets-manager_short}} tool integration to your toolchain template by adding a service definition to the toolchain.yaml file in your template repo. This file is the design blueprint for your toolchain and includes all of the tool integrations that are available when you create a toolchain instance based on that template. To customize an existing toolchain template to include a {{site.data.keyword.secrets-manager_short}} tool integration, insert a YAML definition.

  sm-compliance-secrets:
    service_id: secretsmanager
    parameters:
      name: sm-compliance-secrets
      instance-id-type: instance-name
      region: us-south
      resource-group: default
      instance-name: ffs-secrets
      setup-authorization-type: create

{: codeblock}

Identifying secrets by CRN

{: #identify_secrets_by_crn}

When you configure the {{site.data.keyword.secrets-manager_short}} tool integration to identify secrets by CRN, your toolchain can access arbitrary, key-value, and IAM credential secrets that are stored in the {{site.data.keyword.secrets-manager_short}}. For more information about the different types of secrets in {{site.data.keyword.secrets-manager_short}}, see Working with secrets of different types. You can use only entire key-value secrets for CRN secrets, not individual keys.

Configure {{site.data.keyword.secrets-manager_short}} to securely manage secrets that are part of your toolchain:

If you are configuring this tool integration as you are creating the toolchain, in the Configurable Integrations section, click {{site.data.keyword.secrets-manager_short}}. If {{site.data.keyword.secrets-manager_short}} is defined as an optional tool integration, it is located under More Tools. Choose to identify this instance by the service instance CRN. To create an authorization between the toolchain and the {{site.data.keyword.secrets-manager_short}} service instance select the Create an authorization for this toolchain option from the Authorization type dropdown. This grants the toolchain access to the secret material stored in the {{site.data.keyword.secrets-manager_short}} service instance.
If you have a toolchain and are adding this tool integration to it, from the {{site.data.keyword.cloud_notm}} console, click the Menu icon > Platform Automation > Toolchains. On the Toolchains page, click the toolchain to open its Overview page. Alternatively, on your app's Overview page, on the {{site.data.keyword.contdelivery_short}} card, click View toolchain. Then, click Overview.

a. Click Add tool.

b. In the Tool Integrations section, click {{site.data.keyword.secrets-manager_short}}.
Specify a name for this instance of the {{site.data.keyword.secrets-manager_short}} tool integration to use in your toolchain.
Choose to identify this instance by the service instance CRN.
Specify the CRN of the {{site.data.keyword.secrets-manager_short}} service instance where your secrets are stored. This service instance can exist in a different account if your toolchain is authorized to access secrets in that account.
To create an authorization between the toolchain and the {{site.data.keyword.secrets-manager_short}} service instance click the Create Authorization button. This grants the toolchain access to the secret material stored in the {{site.data.keyword.secrets-manager_short}} service instance.
Click Create Integration.