A required check stays Pending when the workflow that produces it never ran. The usual cause is a path, branch or commit message filter on the workflow. GitHub's documentation says associated checks stay in a Pending state and block merging, and advises against filtering required workflows.
What is happening
Branch protection says "check named X must pass". A pull request that changes only a documentation file may match a path filter that skips your security workflow. No run means no status. The merge button waits for a result that will never arrive.
Three common causes
| Cause | Symptom | Fix |
|---|---|---|
| Path filter on the workflow | Check Pending on docs only changes | Remove the filter from required workflows |
| Branch filter | Pending on certain target branches | Include every protected branch |
| Merge queue without the merge_group trigger | Merge fails when queued | Add the merge_group event |
On the last one, GitHub's documentation states the merge_group event is separate from pull_request and push events, so a workflow must include it for a merge queue to get its check.
Skipped is not always blocked
Job level skips behave differently. A job skipped by a conditional reports Success, so it will not block merging. A job that depends on a failed job is skipped, and the docs suggest using the always function together with needs for required checks that depend on other jobs.
The consequence is easy to miss. A security gate designed as a dependent job can pass with a green tick when its prerequisite fails. We cover that case in a separate post.
Steps to make a required check reliable
- Remove path and branch filters from any workflow whose check is required.
- Move the filtering inside the workflow, so the job runs and exits fast when nothing relevant changed.
- Add the merge group trigger if you use a merge queue.
- Run a test pull request that changes only a docs file, and confirm the check reports.
- Add a test where the scan step fails, and confirm the merge is blocked.
Do not fix it by removing the requirement
When a team is blocked, the quick fix is to remove the check from branch protection. Do not. The check will be forgotten. Fix the workflow instead, and keep the requirement.
Quick check
Why does only my docs change get stuck?
A path filter probably skips the workflow for docs changes, leaving the required check Pending.
Is a skipped job the same as a skipped workflow?
No. A job skipped by a conditional reports Success. A skipped workflow leaves its check Pending.
Safeguard's CI integrations report a status on each pull request, and its policies decide whether that status passes. A free scan is available at gold.safeguard.sh/scan.
Sources
Last reviewed: 19 October 2026.
