GitHub Actions Environment Variable Not Expanding in Steps
An environment variable is empty or appears literally because the expansion syntax is wrong, or because a value set in one step is read in another without being written to GITHUB_ENV.
What this error means
A step prints an empty value, or the literal text ${{ ... }}, where you expected a variable. Setting a variable with export in one step has no effect on later steps.
- run: export VERSION=1.2.3
- run: echo "Deploying $VERSION" # prints "Deploying " - emptyDiagnose 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.
| Where you wrote it | Contexts available there |
|---|---|
run-name | github, inputs, vars |
concurrency | github, inputs, vars |
Top-level env | github, secrets, inputs, vars |
jobs.<id>.if | github, needs, vars, inputs |
jobs.<id>.steps.if | github, needs, strategy, matrix, job, runner, env, vars, steps, inputs |
jobs.<id>.outputs | Full access, including secrets |
Reusable workflow outputs | github, jobs, vars, inputs |
Common causes
Each run step is a fresh shell
A shell variable exported in one run step does not persist to the next. Steps share the job environment only through GITHUB_ENV.
Mixing expression and shell syntax
GitHub evaluates ${{ }} before the shell runs, while $VAR is expanded by the shell. Using the wrong one for the context yields empty or literal output.
How to fix it
Persist values via GITHUB_ENV
Write the variable to GITHUB_ENV so later steps in the same job can read it as an env var.
- run: echo "VERSION=1.2.3" >> "$GITHUB_ENV"
- run: echo "Deploying $VERSION" # now populatedPick the right expansion for the context
- Use ${{ env.VAR }} for workflow expressions evaluated before the shell.
- Use $VAR (or %VAR% on cmd) inside a run script for shell-level expansion.
- Define static values once under a job or step env block.
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 -colorHow to prevent it
- Use GITHUB_ENV (and GITHUB_OUTPUT) to pass values between steps.
- Keep static configuration in a job-level env block.
- Avoid mixing ${{ }} and $VAR for the same value in one command.