Blog ·
Why a skipped workflow blocks your merge

What happens
Say your tests are a required check on main, and you only want them to run when the code changes:
on:
pull_request:
paths:
- 'src/**'Someone opens a pull request that only touches README.md. The workflow doesn’t start, so it never reports. GitHub is still waiting for the check the branch rules require, and the pull request shows it as Expected — Waiting for status to be reported for good. Nobody can merge it without an admin overriding the rules.
GitHub’s docs say a workflow skipped by path filtering, branch filtering or a commit message leaves its checks pending, and they block merging. A job skipped by an if: condition is different: it reports success.
The fix: filter jobs, not workflows
So keep the workflow running on every pull request, and decide inside it which jobs run. A first job looks at what changed. The others run only when their files did. One last job sums it up, and that one is the required check:
name: CI
on:
pull_request:
push:
branches: [main]
jobs:
changes:
runs-on: ubuntu-latest
timeout-minutes: 5
outputs:
app: ${{ steps.filter.outputs.app }}
docs: ${{ steps.filter.outputs.docs }}
steps:
- uses: actions/checkout@v7
- id: filter
uses: dorny/paths-filter@v4
with:
filters: |
app:
- 'src/**'
- 'package.json'
- 'pnpm-lock.yaml'
- '.github/workflows/ci.yml'
docs:
- 'docs/**'
test:
needs: changes
if: needs.changes.outputs.app == 'true'
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@v7
- run: npm ci && npm test
docs:
needs: changes
if: needs.changes.outputs.docs == 'true'
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@v7
- run: npx markdownlint-cli2 "docs/**/*.md"
# The one required check. It passes when every job above passed or was
# skipped, and fails when one failed or was cancelled.
ci-ok:
if: always()
needs: [changes, test, docs]
runs-on: ubuntu-latest
timeout-minutes: 2
steps:
- if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')
run: exit 1Then, in the branch rules, require ci-ok and nothing else. A docs-only pull request skips test, ci-ok passes, and it merges. A code change runs test, and ci-ok fails if it fails.
ci-ok needs both of its lines. if: always() makes it run when a job before it failed or was skipped, which is when it has something to say; without it, it would be skipped too and report success. And it checks for cancelled as well as failure, so a run cut short doesn’t count as a pass.
Four ways it still goes wrong
The filter forgets a file the tests depend on
Put the lockfile, the package manifest and the workflow file itself in the filter. A dependency bump that only touches pnpm-lock.yaml should run the tests, and so should a change to how they run.
The filter matches every pull request anyway
If every pull request bumps a version in package.json, a filter that includes it runs the tests every time. Check it against your last pull requests before you count on the savings: gh api repos/OWNER/REPO/pulls/123/files -q '.[].filename' shows what one touched.
You rename a required job
Required checks are matched by name. Rename test, or the value a matrix puts in its name, and GitHub waits for the old name forever. With one ci-ok as the only required check, you can rename everything else.
A job after it is skipped too
A job that needs a skipped job is skipped as well, even when it has nothing to do with the files. A build or deploy after test stops running on docs changes. Give it if: ${{ !failure() && !cancelled() }}: it then runs when the jobs before it passed or were skipped.
Finding this in your CI
Gating jobs on what changed is one of the first things /make-ci-more-efficient looks for. It measures how many minutes your jobs spend on changes they don’t test, reads your required checks before it touches anything, and writes the gate job above for you when it’s worth it.
npx skills add https://checklane.sh --skill make-ci-more-efficient -a claude-codeThen type /make-ci-more-efficient in Claude Code, or tell it your CI is slow.