# Give a job a secret

Hand a secret from your organization's secrets to a workflow job, and know what is masked in its log.

Replace _NPM_TOKEN_ with the secret's name.

## Prerequisites

- The secret exists under **Secrets** with exactly the name the workflow uses.
- The secret is granted to the `actions` consumer for this repository, or for every repository
  (see [Grant a consumer access to a secret](/docs/secrets/guide/grant-a-consumer)).
- The IAM user who starts the run may `secrets:GetSecretValue` on the secret. A re-run keeps the
  original run's user (see
  [Use a secret in a workflow](/docs/secrets/guide/use-a-secret-in-a-workflow)). A run that records
  no IAM user (an SSH push, a push to a pull request's branch) fails when a job needs a secret, with
  "This run has no triggering IAM user, so no policy can be evaluated and secrets are withheld. …".

## Name the secret in the workflow

In the native format, list it on the job and read it in a value:

```yaml
jobs:
  publish:
    secrets: [NPM_TOKEN]
    steps:
      - run: npm publish
```

Each listed secret is exported into that job's `run` steps under its own name and is available as
`${{ secrets.NPM_TOKEN }}`. A job that does not list it does not have it. With
`environment: <slug>`, the job reads that secrets environment's value.

In a GitHub-syntax workflow, write `${{ secrets.NPM_TOKEN }}` where you need it; there is no list.
A name your organization does not define reads as empty, as on GitHub. A job with `environment:`
reads the secrets environment of the same slug first.

## Result

The run's jobs get the secret's active version. When a secret is not granted, or the person who
started the run may not read it, the run fails before any job starts, with a message such as
`Secret "NPM_TOKEN" is not granted to CI for this repository. Grant it under Secrets (open the secret, then Consumers), then re-run.`
For a secret the person may not read the message is
`The user who triggered this run is not allowed to read secret "NPM_TOKEN"`. When the message
begins `Secret "…"`, the failed run's page offers **Grant _NPM_TOKEN_ to CI** (the secret exists) or
**Create _NPM_TOKEN_** (it does not).

## What is masked

A secret's value is replaced with `***` in the log: the value itself, each line of a multi-line
value, and its base64, URL-encoded and JSON-escaped forms, also when a step prints it in pieces.
A value shorter than four characters is not masked. A step that transforms the value otherwise
(reverses it, prints every second character) puts the result in the log in plain text.

## GitHub's download rate limit

On the one-machine-per-run hosted machines, a secret named `GITHUB_TOKEN`, granted and readable
like any other, becomes the job's `github.token`; without one it is empty. Store a GitHub token
there, and actions that send `github.token` along when they download from GitHub, such as the
`setup-*` actions, are no longer held to GitHub's limit for anonymous requests.

## Related

- [Use a secret in a workflow](/docs/secrets/guide/use-a-secret-in-a-workflow)
- [Deploy with an OIDC token](deploy-with-oidc.md)
- [Protect a deployment with an environment](protect-a-deployment.md)
