GitHub Actions "Job has been skipped" (needs) - Why & Fix
A job with needs only runs if all needed jobs succeeded, by default. If any needed job is skipped or fails, the dependent job is skipped unless its if uses a status function.
What this error means
A job that should run after others is marked skipped, because an upstream job in needs was skipped or did not succeed.
Job 'deploy' has been skipped because a job it depends on did not complete successfully.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.
| 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
Upstream job skipped or failed
Default needs semantics require all dependencies to succeed.
Conditional upstream job did not run
A needed job gated by if that evaluated false propagates a skip downstream.
How to fix it
Override the run condition explicitly
- Add an if with a status function: if: always() or if: \${{ !cancelled() }}.
- Check upstream outcomes via needs.<job>.result when you only want some paths.
- Be deliberate: always() runs even on failure, so guard accordingly.
deploy:
needs: [build, test]
if: ${{ !cancelled() && needs.build.result == 'success' }}
runs-on: ubuntu-latest
steps:
- run: ./deploy.shCatch 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
- Decide intent: skip-on-upstream-skip (default) vs run-anyway (status functions).
- Inspect needs.<job>.result to branch precisely.