GitHub Actions Reusable Workflow Outputs Empty in the Caller
A caller reads a reusable workflow’s output and gets an empty string. workflow_call outputs must be declared and mapped from a job output inside the reusable workflow, then consumed via needs.<job>.outputs in the caller.
What this error means
After calling a reusable workflow with uses:, the caller reads needs.<job>.outputs.<name> and gets nothing, even though a step inside the reusable workflow produced the value.
# caller
jobs:
build:
uses: ./.github/workflows/build.yml
use:
needs: build
steps:
- run: echo "${{ needs.build.outputs.version }}" # 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
workflow_call outputs not declared
A reusable workflow only surfaces outputs listed under on.workflow_call.outputs. A step or job output alone does not reach the caller.
Output not mapped from a job
Each workflow_call output must reference a job output via jobs.<id>.outputs. Skipping that mapping leaves the caller-visible output empty.
How to fix it
Declare and map the workflow_call output
Expose the output at the workflow_call level, sourced from a job output that itself maps a step output.
# build.yml (reusable)
on:
workflow_call:
outputs:
version:
value: ${{ jobs.compile.outputs.version }}
jobs:
compile:
runs-on: ubuntu-latest
outputs:
version: ${{ steps.v.outputs.version }}
steps:
- id: v
run: echo "version=1.2.3" >> "$GITHUB_OUTPUT"Read it via needs in the caller
- Add needs: on the consuming job so it waits for the reusable call.
- Reference needs.<call-job>.outputs.<name> in the caller.
- Confirm each name lines up: step output → job output → workflow_call output.
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
- Declare workflow_call outputs and chain them from job and step outputs.
- Keep output names consistent across the three levels.
- Echo the value inside the reusable workflow to confirm it is non-empty.