GitHub Actions needs.<job>.outputs Undefined Across Jobs
A downstream job reads needs.<job>.outputs.<name> and gets nothing because the upstream job did not expose that value as a job output, or the job is not listed in needs.
What this error means
A consumer job sees an empty value from needs.<job>.outputs even though the producing step set a step output. The data does not cross the job boundary.
jobs:
build:
runs-on: ubuntu-latest
steps:
- id: v
run: echo "ver=1.0.0" >> "$GITHUB_OUTPUT"
deploy:
needs: build
runs-on: ubuntu-latest
steps:
- run: echo "${{ needs.build.outputs.ver }}" # empty: build never mapped itDiagnose 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
Job output not mapped from the step output
Step outputs are local to a job. To cross jobs, the producing job must declare jobs.<id>.outputs and map each one to a steps.<id>.outputs reference.
Consumer missing needs on the producer
The needs context only contains jobs the current job depends on. Without needs: build, needs.build is unavailable.
How to fix it
Map step outputs to job outputs
jobs:
build:
runs-on: ubuntu-latest
outputs:
ver: ${{ steps.v.outputs.ver }}
steps:
- id: v
run: echo "ver=1.0.0" >> "$GITHUB_OUTPUT"
deploy:
needs: build
runs-on: ubuntu-latest
steps:
- run: echo "${{ needs.build.outputs.ver }}"Verify the dependency chain
- List every producer in the consumer job needs.
- Match the job output name in the producer to the needs reference.
- Remember a skipped or failed producer leaves its outputs empty.
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
- Always declare jobs.<id>.outputs when another job consumes a value.
- Keep output names identical between producer and consumer.
- Guard consumers with if: needs.<job>.result == 'success' where appropriate.