Use a secret in a workflow

Hand a secret to one workflow job as ${{ secrets.NAME }}, for one repository only.

Last updated 18 November 2026View as Markdown

Replace STRIPE_API_KEY with the secret's name.

Prerequisites

  • An actions grant on the secret that covers the repository (scoped to it, or for every repository); see Grant a consumer access to a secret.
  • The IAM user who starts the run holds secrets:GetSecretValue on the secret. A run that records no IAM user gets no secrets: a push over SSH, a push to a pull request's branch, and a pull request reopened by someone other than its author. A re-run keeps the original run's user.

Name the secret in the job

In a workflow under .ews/workflows/, list the secret under the job's secrets: and read it as ${{ secrets.STRIPE_API_KEY }}. Only the jobs that list a secret get it. To get an environment's own value rather than the Default, add environment: <slug> to the job (see Environments). See the workflow reference.

A workflow in GitHub Actions syntax (under .github/workflows/) has no secrets: list: every ${{ secrets.NAME }} in the file is resolved for the run, and a name your organization does not define reads as empty instead of stopping the run.

What is checked

Before a job's secrets are decrypted, for each name the job lists:

  1. the secret exists in the job's environment or as a Default;
  2. an unexpired actions grant covers this repository;
  3. the IAM user who triggered the run may secrets:GetSecretValue on it.

If one fails, the run stops before the job starts, with one of these messages:

  • Without environment:: Secret "STRIPE_API_KEY" does not exist in this organization. Create it under Secrets, grant it to CI for this repository, then re-run.
  • With environment:: Secret "STRIPE_API_KEY" exists neither in this job's environment nor as a shared secret. Create it under Secrets, grant it to CI for this repository, then re-run.
  • For an environment: slug that names no environment: environment: staging — there is no secrets environment with that slug in this organization
  • Secret "STRIPE_API_KEY" is not granted to CI for this repository. Grant it under Secrets (open the secret, then Consumers), then re-run.
  • The user who triggered this run is not allowed to read secret "STRIPE_API_KEY"
  • This run has no triggering IAM user, so no policy can be evaluated and secrets are withheld. Start the workflow from the console (workflow_dispatch), or drop the job's secrets: list.

A run whose trigger recorded no IAM user cannot have a policy evaluated, so its secrets are withheld rather than trusted.

Result

The job gets the active version. The read is written to the secret's access log as the actions consumer, with the run number.

Did this page help you?