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.

Last updated 18 November 2026View as Markdown

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).
  • 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). 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:

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.

Did this page help you?