Documentation Grafana Cloud Alerts and IRM Workflows Manage secrets

Manage secrets

Secrets let you reference sensitive values like API tokens without including them in workflow definitions. The Workflows app ships an in-plugin Secrets page that you should use as the default path for managing secrets. Secrets created elsewhere through Grafana Secrets Management can also be referenced from a workflow as long as the Workflows decrypter is allowed.

Before you begin

To create or use secrets in workflows, you need:

• Access to the Workflows app in your Grafana Cloud stack
• The Workflows Editor role for the in-plugin Secrets page, or equivalent permissions on Grafana Secrets Management for the alternative path

Create a secret in the Workflows app

The in-plugin Secrets page is the recommended way to create and manage secrets used by your workflows. Secrets created here are automatically configured with the Workflows decrypter, so no extra configuration is required.

To create a secret:

1. In Grafana, navigate to More apps and open the Workflows app.
2. Open the Secrets page from the left navigation.
3. Click Create secret.
4. Enter a Name. The name becomes part of the URI you reference in the workflow.
5. Enter a Description.
6. Enter the Value.
7. Optionally, add labels.
8. Click Create.

The secret is now available to any workflow in the same stack.

Reference a secret in a workflow

Declare secret references in the resources.secrets section of the workflow definition. Each entry maps a reference name to a secret URI in the form secret://<secret-name>.

YAML Copy

spec:
  resources:
    secrets:
      api-token: "secret://my-api-token"
  steps:
    - id: call-api
      type: http.call
      inputs:
        method: "GET"
        url: "https://api.example.com/data"
        authMethod: "bearer"
        authSecret: "${resources.secret.api-token}"

In this example:

• my-api-token is the secret name as it appears on the Secrets page.
• api-token is the reference name you use inside the workflow.
• ${resources.secret.api-token} is replaced with the resolved secret value at step execution time.

Use secret references in step inputs

Step inputs reference secrets using ${resources.secret.<key>} syntax, where <key> is the reference name defined in resources.secrets.

For keys with special characters, use bracket notation:

text Copy

${resources.secret["my-api-token"]}

Edit or delete a secret

To update or remove a secret:

1. Open the Secrets page in the Workflows app.
2. Find the secret in the table.
3. Use the row actions to edit the value, description, or labels, or to delete the secret.

If a workflow references a secret that no longer exists, the run fails at the step that needs it. For details on what shows up in the editor when this happens, refer to Troubleshoot workflows.

Alternative: Use Grafana Secrets Management

Secrets created in Grafana Secrets Management can also be referenced from a workflow. Use this path when you need to share a secret with multiple Grafana apps.

To create a secret in Grafana Secrets Management for use with Workflows:

1. Create the secret in the Grafana Cloud UI or through the Grafana Secrets Management API.
2. Add the Workflows decrypter so the workflow engine can resolve the secret at execution time.
3. Note the secret name.

Reference the secret in the workflow with the secret:// URI prefix followed by the secret name. For secrets organized into a path, include each segment, for example, secret://gsm/my-secret.

Understand secret scoping and resolution

• Secrets are scoped to your Grafana Cloud stack. A secret created in stack A is not visible to a workflow running in stack B.
• Each workflow run resolves secrets using the stack identity of the triggering event.
• The engine resolves secrets at execution time and redacts them from step logs.

Next steps

• Create workflows
• Load incident data
• Load alert group data
• Use CEL expressions
• Troubleshoot workflows
• Step and trigger types reference