# Use a secret in a workflow

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

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](grant-a-consumer.md).
- 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](environments.md)). See the [workflow reference](/docs/workflows).

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.

## Related

- [Grant a consumer access to a secret](grant-a-consumer.md)
- [See who has read a secret](see-who-has-read-a-secret.md)
