Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 44 ยท GitHub Actions Basics

Secrets, Variables and Environment Variables

Understand env at workflow, job and step level, repository variables versus encrypted secrets, log masking, GITHUB_TOKEN permissions and fork behavior.

Almost every pipeline needs configuration, and some of it must stay private: an API token for publishing a package, a password for a test database, a key for a cloud account. GitHub Actions gives you three tools. Environment variables (env) pass ordinary values to steps. Variables (the vars context) store non-sensitive settings in the repository settings. Secrets store sensitive values encrypted and hide them in logs.

Choosing the right tool is half of pipeline security. The other half is not leaking what you stored. This lesson covers all three, the automatic GITHUB_TOKEN, what happens with pull requests from forks, and the rules for keeping secrets out of logs. The workflow files are read-only (they need GitHub). The runnable example is a stand-in log masker that shows what masking can and cannot do; GitHub's real masking is implemented inside the runner.

Environment variables at three levels

env can be set on the whole workflow, on a job or on a single step. The closest level wins:

YAML
name: Env levels
on: [push]

env:
  APP_ENV: ci
  REGION: eu-west-1

jobs:
  report:
    runs-on: ubuntu-latest
    env:
      REGION: us-east-1
    steps:
      - name: Show values
        env:
          APP_ENV: debug
        run: |
          echo "APP_ENV=$APP_ENV"
          echo "REGION=$REGION"
      - name: Back to the job level
        run: echo "APP_ENV=$APP_ENV REGION=$REGION"

The first step prints APP_ENV=debug and REGION=us-east-1. The second prints APP_ENV=ci REGION=us-east-1. The step value overrides the workflow value only for that step.

flowchart TD
  W["workflow env<br/>APP_ENV=ci, REGION=eu-west-1"] --> J["job env<br/>REGION=us-east-1"]
  J --> S["step env<br/>APP_ENV=debug"]
  S --> R["step sees<br/>APP_ENV=debug, REGION=us-east-1"]

Each level overrides the one above it, and the narrowest value reaches the step.

Remember the difference between the two ways to read a value. In a shell script, $APP_ENV is read by the shell at run time. The expression ${{ env.APP_ENV }} is replaced by GitHub before the shell starts. Both work in a run step, but only the expression form works in places that are not shell scripts, such as with: or if:. Variables written to GITHUB_ENV in one step appear in later steps; see Jobs, Steps and Dependencies.

Every runner also sets default variables such as GITHUB_REPOSITORY, GITHUB_SHA, GITHUB_REF_NAME, RUNNER_OS and CI=true. Many tools check CI=true to switch to non-interactive output.

Variables versus secrets

Both live in the repository (or organization, or environment) settings and are read through contexts:

YAML
steps:
  - run: echo "Deploying to ${{ vars.DEPLOY_REGION }}"
  - run: ./publish.sh
    env:
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
vars secrets
For Names, regions, feature switches, URLs Tokens, passwords, private keys
Stored Readable in settings Encrypted, write-only after saving
In logs Shown as plain text Replaced by ***
Rule Fine to expose Never print, never commit

If you are unsure, ask: would it hurt if this appeared on a public web page? If yes, it is a secret. Values can be defined at three scopes: organization, repository and environment. A secret in an environment (such as production) is only available to jobs that target that environment, which can also require approval. See Environments, Approvals and Deployments.

Never hard-code a secret in the workflow file or the repository, even in a private repository. Once it is in Git history it is hard to remove. If it happens anyway, treat the value as compromised and rotate it (create a new one and revoke the old one).

How masking works, and where it stops

When a job starts, the runner learns the values of the secrets it may use and replaces them with *** wherever they appear in the log. This is helpful, but it is only exact text matching:

  • A transformed value is not reliably recognised. The runner may catch a few common encodings, but a script that reverses the secret, puts spaces between the letters or splits it over two lines will show it in full. Never depend on masking to fix a printed secret.
  • A secret that is short or common (like true or 1) can cause odd masking or be useless.
  • A structured secret, such as a JSON blob stored as one secret, is masked as a whole, but its individual fields are not. Store each sensitive piece as its own secret.
  • Values that are derived at run time (for example a token returned by an API call) are not secrets as far as the runner knows. Register them with the workflow command ::add-mask:::
YAML
- name: Mask a runtime value
  run: |
    TOKEN=$(./fetch-temporary-token.sh)
    echo "::add-mask::$TOKEN"
    echo "TOKEN=$TOKEN" >> "$GITHUB_ENV"

Treat masking as a safety net, not as a license to print secrets. The habits that keep secrets safe are simple:

  • Pass a secret to a step through env:, then use the environment variable in the script. Do not paste ${{ secrets.X }} inside the script text.
  • Do not run commands that echo the environment (env, printenv, set -x in a script that uses secrets).
  • Do not write secrets into files that become artifacts or caches.
  • Prefer short-lived credentials, such as OIDC tokens, over long-lived keys when your cloud provider supports it.

GITHUB_TOKEN and permissions

Each workflow run gets an automatic token, available as secrets.GITHUB_TOKEN (and as github.token). It lets the workflow talk to the GitHub API: comment on a pull request, create a release, push a package. It exists only for the duration of the run, and its power is set by the permissions key:

YAML
permissions:
  contents: read

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      packages: write
    steps:
      - uses: actions/checkout@v4

Two rules matter. First, as soon as you write a permissions block, every permission you do not list drops to none, so you grant exactly what is needed. Second, a job-level block replaces the workflow-level block for that job. A good default is contents: read for the whole workflow and extra rights only on the job that needs them. The default for a repository can also be restricted in its settings, but an explicit block makes the workflow's intent visible. This is the first step of Securing Your Pipeline.

Secrets and pull requests from forks

When a workflow is triggered by a pull_request from a fork, GitHub does not pass repository secrets to it, and GITHUB_TOKEN is read-only. Otherwise anyone could open a pull request that prints your secrets. Only GITHUB_TOKEN is always available. This means jobs that need secrets (deploys, publishing) will not work for fork pull requests, which is the intended behavior.

The pull_request_target event runs in the context of the base repository and does receive secrets, which is why it is dangerous when combined with a checkout of the pull request's code. Do not run untrusted code with secrets. Triggers are covered in Triggers: push, pull_request, schedule and More.

Stand-in: a log masker

The model below takes a list of secret values and a log, and replaces exact matches with ***, just as the runner does. Then it shows the three situations from this lesson: a secret printed directly, the same secret with its letters separated (not masked) and a runtime value that was registered with add-mask. Note that the demo uses made-up values only.

JS What masking catches and what it misses

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Line 1 is safe, line 2 shows that a simple transformation defeats exact matching, and the runtime token is hidden only after it is registered.

Stand-in: resolving env levels and permissions

The second model reproduces two rules from this lesson in a few lines: closest-level env wins, and a permissions block that names anything leaves all other scopes at none.

JS Env precedence and permission defaults

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The permissive-default line is an illustration of a repository that grants broad rights by default; your own repository's default may be read-only. The lesson is the same: write the block yourself.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. The workflow sets env REGION=eu-west-1, the job sets REGION=us-east-1 and the step sets nothing. What does the step see?

    The closest level wins. The job value overrides the workflow value, and the step does not override anything.
  2. 2. Which value belongs in vars rather than secrets?

    A region name is configuration that is harmless if seen. Tokens, passwords and keys must be secrets.
  3. 3. A script prints a secret with a space between every letter. What does the log show?

    Masking replaces the secret's text. Transformed values are not reliably recognised, so avoid printing secrets in any form.
  4. 4. A workflow has permissions: contents: read. What is the permission for pull-requests?

    Writing a permissions block sets every unlisted permission to none. List only what the workflow needs.
  5. 5. A pull request from a fork triggers a workflow with the pull_request event. Are repository secrets available?

    GitHub withholds secrets from fork pull requests so that a malicious pull request cannot print them.

Summary

  • env can be set on the workflow, job and step; the narrowest level wins. $NAME is read by the shell, ${{ env.NAME }} by GitHub before the step starts.
  • Use vars for harmless configuration and secrets for anything sensitive; scope secrets to environments for protection and approvals.
  • Masking replaces exact secret values with ***; transformed or derived values can slip through unless registered with ::add-mask::. Pass secrets through env: and never echo them.
  • GITHUB_TOKEN is per-run; set permissions explicitly, starting from contents: read, because unlisted scopes become none.
  • Fork pull requests do not receive secrets and get a read-only token; be very careful with pull_request_target.

Next: CI for Node and Python Projects