If a required check belongs to a workflow with a paths: filter, a pull request that doesn't touch those paths waits
forever: the workflow never starts, so the check never reports, and GitHub shows "Waiting for status to be reported."
The fix is to stop filtering the workflow. Let it start on every pull request and skip the expensive jobs inside it with
if:, because a job skipped by a condition counts as passed. Then decide what to skip by the content of the files a
check reads, rather than by the paths a diff touched. That last part is what took my CI from running out of minutes to
skipping most of its work, safely.
Why the check stays pending#
GitHub's troubleshooting guide for required checks says it plainly: a workflow skipped because of path filtering, branch filtering or a commit message leaves its checks pending, and a pull request that requires them can't merge. The same page notes the other half, the one that makes everything below work: a job that is skipped because of a conditional reports success.
So there are two kinds of skip, and they behave in opposite ways:
| Skipped by | The required check |
|---|---|
on: pull_request: paths: (filter) | Never reports: pending |
A job's if: that is false | Reports: counts as pass |
The usual workaround, and its catch#
The workaround GitHub used to document (its page now only says to avoid requiring workflows that can be skipped) is a
second workflow with the same name and the same job names, triggered by paths-ignore with the opposite list, whose
jobs only echo something and succeed. Every pull request then reports the check: the real workflow or the stand-in.
It unblocks merges, and it has three costs:
- Two path lists to keep in step by hand, in two files. When they drift, a pull request either runs both or is blocked again.
- A pass nobody earned. The stand-in reports green for a change it never tested. That is fine only as long as the path list really names every file the check depends on.
- Paths are a property of the diff, not of what gets tested. A merge commit, a rebase, or a re-run tests a tree, and the question that matters is whether that tree's inputs were tested before, not which files one diff touched.
Skip by content instead of paths#
The idea: give each check a key made from the exact content of the files it reads. When the check passes, record that
key. When a later run has the same key, on any branch, the check already passed on those inputs, so skip it with
if:.
Git already gives every file's content an id: the blob id. Hashing the ids of a check's input files gives a key that changes when, and only when, one of those files does:
# The key of the API check's inputs in the commit being tested.
git ls-tree -r HEAD -- api Makefile .github/workflows/ci.yml | sha256sum | cut -c1-40A pass is recorded as a workflow artifact named after the check and its key. Artifacts expire, so a pass lasts as long as its retention (14 days here), and every check still runs at least every two weeks. A plan job, first in the workflow, looks for a pass with the current key and tells each check whether to run:
name: ci
on:
pull_request: {}
push:
branches: [main]
workflow_dispatch: {}
jobs:
plan:
runs-on: ubuntu-latest
permissions:
contents: read
actions: read # read earlier runs' artifacts
outputs:
api: ${{ steps.plan.outputs.api }}
api_key: ${{ steps.plan.outputs.api_key }}
steps:
- uses: actions/checkout@v7
- id: plan
env:
GH_TOKEN: ${{ github.token }}
run: |
key=$(git ls-tree -r HEAD -- api Makefile .github/workflows/ci.yml | sha256sum | cut -c1-40)
echo "api_key=$key" >> "$GITHUB_OUTPUT"
# Unexpired passes of this repository's own runs: a fork's run can upload one too.
found=$(gh api "repos/$GITHUB_REPOSITORY/actions/artifacts?name=pass-api-$key" \
--jq '[.artifacts[] | select((.expired | not)
and .workflow_run.head_repository_id == .workflow_run.repository_id)] | length' || echo 0)
if [ "$GITHUB_EVENT_NAME" != workflow_dispatch ] && [ "$found" -gt 0 ]; then
echo "api=false" >> "$GITHUB_OUTPUT"
else
echo "api=true" >> "$GITHUB_OUTPUT"
fi
api:
needs: plan
if: needs.plan.outputs.api == 'true'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- run: make test
- run: echo "${{ needs.plan.outputs.api_key }}" > pass.txt
- uses: actions/upload-artifact@v7
continue-on-error: true
with:
name: pass-api-${{ needs.plan.outputs.api_key }}
path: pass.txt
retention-days: 14
overwrite: truePin the actions to commit SHAs in your own copy. A few details make it safe:
- When in doubt, run. If GitHub's API doesn't answer, the plan finds no pass, and the check runs. A pass is only ever a reason to skip.
- A manual run runs everything.
workflow_dispatchignores passes, for the day you suspect one. - Only your own runs count. A pull request from a fork runs in your repository, and its run can upload an artifact
of the same name without testing anything. The
jqfilter keeps only artifacts whose run came from the repository itself (in the artifact'sworkflow_run,head_repository_idequalsrepository_id). - Recording a pass never fails a check. Mark the upload
continue-on-error: full artifact storage shouldn't turn a green test red. - Make the plan job required too. When a job fails, the jobs that need it are skipped, and skipped counts as passed. A required plan job makes a broken plan block the merge instead.
A check's inputs are a promise#
The whole thing is only as good as each check's list of inputs. If a test starts reading a file outside its list,
a change to that file alone keeps the check skipped. I keep the lists in one script, each check on one line, with a
rule for each path: an input (+) or not (-), the longest matching rule winning. Every test check also reads the
workflow file, the shared scripts and the Makefile, so a change to how checks run reruns every test. A pull request's
image builds are the exception: their inputs are what the Docker build reads.
Some inputs aren't files in the repository at all: a vulnerability database, a base image, a dependency resolved at run time. The 14-day expiry bounds how stale those get.
What it changed#
My repository is private, and its plan includes 3,000 Actions minutes a month. In October 2026 they ran out on the 25th. Looking at where they went: the API's job was 45% of them, and the runs on pushes to the main branch, right after each merge, were 41%. Of those merge runs, 65% re-tested a tree its pull request had already tested, byte for byte. Every push to a pull request cost about 20 billed minutes, every merge about 25.
With the plan job, a merge whose tree its pull request tested skips straight to building the images: they're ready about 6 minutes after the merge instead of 15. A change to the website alone runs the website's check alone. The job summary says, for each check, whether it ran and why, with a link to the run whose pass it reused.
Where this came from#
This is the CI of Swingback, a feedback tool whose one repository holds an API, a web app, a website and five SDKs. If your feature requests live in GitHub issues next to all this, here is when issues are enough, and when to add a board.
