GitHub Actions Environment Variables and Their Scope

By Daniel Zoghalchali·Latchkey

A variable exported in one run step is gone in the next, because each step is a separate shell. Persisting one means writing to $GITHUB_ENV, not exporting it.

Two rules explain nearly every environment-variable surprise in Actions: each run step is its own shell process, so nothing exported survives to the next step, and env values are evaluated by the runner before the shell sees them.

That second rule is why ${{ env.FOO }} and $FOO can produce different results in the same line.

Default variables worth knowing

Persisting a value between steps

# WRONG: each run step is a separate shell
- run: export MY_VAR=hello
- run: echo "$MY_VAR"          # empty

# RIGHT: append to $GITHUB_ENV
- run: echo "MY_VAR=hello" >> "$GITHUB_ENV"
- run: echo "$MY_VAR"          # hello

# step OUTPUT rather than an env var
- id: build
  run: echo "version=1.2.3" >> "$GITHUB_OUTPUT"
- run: echo "${{ steps.build.outputs.version }}"

# multiline needs a delimiter
- run: |
    {
      echo 'NOTES<<EOF'
      cat CHANGELOG.md
      echo EOF
    } >> "$GITHUB_ENV"

Precedence and evaluation order

• Step env overrides job env, which overrides workflow env.
• ${{ env.FOO }} is substituted by the runner before the shell runs; $FOO is expanded by the shell at execution time.
• That difference matters for anything set during the same step, and for values containing shell metacharacters.
• Secrets are masked in logs, but a secret written to $GITHUB_ENV and later echoed deliberately can still be exposed through transformations.
• vars are configuration variables from the repository, organisation, or environment, and are not the same as env.

Writing to the job summary

- run: |
    {
      echo "## Test results"
      echo ""
      echo "| Suite | Result |"
      echo "|-------|--------|"
      echo "| unit  | pass   |"
    } >> "$GITHUB_STEP_SUMMARY"

Diagnose it: print the context before you change anything

Most workflow-expression bugs are not syntax errors, they are an expression reading something that is empty. GitHub resolves a missing property to an empty string instead of failing the run, so a wrong reference looks like a logic bug rather than a mistake. Dump the contexts first and you will usually see the answer immediately.

- name: Dump contexts
  run: |
    echo '--- github ---'   ; echo '${{ toJSON(github) }}'
    echo '--- needs ---'    ; echo '${{ toJSON(needs) }}'
    echo '--- steps ---'    ; echo '${{ toJSON(steps) }}'
    echo '--- matrix ---'   ; echo '${{ toJSON(matrix) }}'
    echo '--- inputs ---'   ; echo '${{ toJSON(inputs) }}'

Check the context is allowed where you used it

Contexts are not available everywhere. The same expression can be valid in a step if and invalid in a job if, which is why an expression that works in one workflow fails when moved.

Catch it before it reaches CI

Every failure in this cluster is statically detectable. actionlint parses workflow expressions, checks context availability against the same rules above, and validates needs references, so these bugs never need to cost you a run.

# one-off
docker run --rm -v "$(pwd):/repo" --workdir /repo rhysd/actionlint:latest -color

# as a job, before anything expensive runs
- uses: actions/checkout@v4
- run: |
    bash <(curl -s https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)
    ./actionlint -color

Frequently asked questions

Related guides

References

• GitHub: variables reference (verified 2026-08-20)
• GitHub Actions contexts reference (verified 2026-08-20)
• GitHub Actions documentation
• Workflow syntax for GitHub Actions