Secrets & Environments

## What a GitHub Actions secret is A secret is an encrypted string stored by GitHub at repository, organization, or environment level. Once saved it is never displayed again in the UI or returned by the API. When a run starts, the secrets in scope for that run are decrypted and exposed to the job through the `secrets` context, read with expression syntax: `${{ secrets.MY_SECRET }}`. Secret names are case-insensitive, may contain only alphanumeric characters and underscores, may not begin with a number, and may not begin with `GITHUB_`, which is reserved. ## The two places you consume one **As an action input.** Most actions that need a credential take it as an input: - uses: docker/login-action@v3 with: username: ${{ secrets.REGISTRY_USER }} password: ${{ secrets.REGISTRY_PASSWORD }} **As an environment variable for a `run:` step.** Declare it under `env:` on the step (or the job) and read it from the shell: - run: ./deploy.sh env: DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }} What you should avoid is putting the expression inside the command text itself, such as `run: ./deploy.sh --token=${{ secrets.DEPLOY_TOKEN }}`. Expressions are evaluated by the runner and the result is written into the script file **before** the shell runs it. A secret whose value contains a double quote, a backtick, a `$(` sequence, or a newline can therefore terminate the intended command and execute something else. Passing through `env:` avoids the problem completely, because the value travels in the process environment and is never re-parsed as source text. The same reasoning is why the same rule applies to untrusted expression values such as a pull-request title. ## Masking, and what it does not do When a secret is provided to a job, the runner registers its value with the log service. If that exact string later appears in step output, it is replaced with `***`. You can register additional values yourself with the `add-mask` workflow command: echo "::add-mask::$DERIVED_TOKEN" Masking is best-effort string replacement on the log stream. It does not survive transformations: if a step base64-encodes the secret, prints it one character per line, or writes it into an uploaded artifact, nothing is redacted. It also does not restrict access — every step in the job, including a third-party action you called, runs in the same environment and can read the same values. This is why third-party actions are pinned and reviewed, and why you scope secrets to the jobs that genuinely need them rather than declaring them in workflow-level `env`. Storing structured data such as a whole JSON blob in one secret is discouraged for the same reason: only the exact stored string is masked, so individual fields printed by a tool that parsed the JSON come out in clear text. ## Where secrets are not available Runs triggered by `pull_request` from a forked repository receive no secrets — the expressions evaluate to empty strings — and a read-only `GITHUB_TOKEN`. That is deliberate: the workflow file and the code it runs come from a contributor you have not vetted. A job that references an environment gets that environment's secrets only after the environment's protection rules pass. And a reusable workflow invoked with `workflow_call` receives no secrets unless the caller passes them explicitly or with `secrets: inherit`. ## Practical checklist - Read secrets through `secrets.NAME`; never commit one, and never echo one to debug. - Bind them with `env:` or `with:`, at the narrowest scope that works — step over job, job over workflow. - Treat masking as a typo net, not a control; assume any step in the job can exfiltrate what the job can see. - Expect empty values on fork pull requests, and design workflows that need credentials to run on a trusted trigger instead. - Prefer short-lived credentials (the job's `GITHUB_TOKEN`, or a cloud token obtained through OIDC) over a stored long-lived secret whenever the target supports it.