GitHub Actions "Skipping this check because the workflow file is invalid on this ref"
GitHub evaluates the workflow file as it exists on a specific ref. If that file is invalid on the ref backing a required check, the check is skipped rather than run - leaving merge blocked with no failing job.
What this error means
A required check never runs and merge is blocked; the run page notes the workflow is invalid on the ref.
Skipping this check because the workflow file is invalid on this ref.
The workflow file has a syntax or schema error on the branch backing this check.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
Invalid workflow on the base or head ref
A YAML/schema error on the ref GitHub evaluates means the workflow cannot be compiled, so the check is skipped.
Required check name no longer produced
A renamed or invalid job means the required check name is never reported.
How to fix it
Fix the workflow on the relevant ref
- Open the workflow on the ref noted in the message and fix the YAML/schema error.
- Confirm the job that produces the required check name still exists.
- Push so the check can run.
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
- Lint workflow files in CI on every change.
- Keep required-check names in sync with the jobs that emit them.