| name | pr-ci-health |
| description | Prevent and diagnose "PR created but GitHub Actions never start" situations. Use on EVERY commit/push/PR-creation flow in this repo (including commit-commands:commit-push-pr) — rebase onto origin/main before pushing — and whenever `gh pr checks` shows "no checks reported", checks stay absent after a push, or CI seems stuck without any runs. |
PR CI Health: prevent & diagnose missing GitHub Actions runs
A PR that conflicts with main cannot get a test merge commit
(refs/pull/N/merge), so pull_request-triggered workflows never start —
the PR sits at "no checks reported" indefinitely (this happened on PR #13).
This skill bakes prevention into every push and gives the diagnosis flow for
when checks still fail to appear.
Prevention — before every push / PR creation
git fetch origin main- Check divergence:
git rev-list --left-right --count origin/main...HEAD
(left = commits you are behind)
- If behind:
git rebase origin/main — git merge is forbidden
- If conflicts: resolve one by one,
git rebase --continue, then run quality
gates (pnpm typecheck && pnpm lint && pnpm test) before pushing
- Push (
--force-with-lease if the branch was already pushed), then monitor:
sleep 10 && gh pr checks --watch in foreground, timeout 600000ms
Diagnosis — "no checks reported" after PR creation or push
Work through these in order; at the end, report what was checked and what the
cause was.
- Are runs really absent?
gh run list --branch <branch> --limit 5
- Runs exist as queued/pending → CI is just slow; keep watching.
- Merge conflict? (most common)
gh pr view <N> --json mergeable,mergeStateStatus
CONFLICTING → rebase onto origin/main, resolve, run quality gates,
git push --force-with-lease, then wait for checks to register:
until gh run list --branch <branch> --limit 1 | grep -q .; do sleep 5; done
and re-run gh pr checks --watch.UNKNOWN → GitHub is computing mergeability asynchronously; re-query
2-3 times a few seconds apart before concluding.
- GitHub Actions incident?
curl -s https://www.githubstatus.com/api/v2/components.json — check the
"Actions" component. If degraded, do NOT retrigger; report the incident and
suggest waiting for recovery.
- Retrigger (last resort): empty commit to fire a
synchronize event —
git commit --allow-empty -m 'chore: retrigger CI' + push. Still nothing?
gh pr close <N> && gh pr reopen <N>.
Fallback — merging without CI when Actions is unstable
CI runs the exact same quality gates as local
(pnpm typecheck && pnpm lint && pnpm test), so when GitHub Actions itself is
the problem, local gates are an acceptable substitute (see "CI fallback
policy" in CLAUDE.md):
- Confirm the cause is Actions instability, not the PR: no merge conflict
(step 2 above) and either a githubstatus incident on the Actions component
or checks that stay absent/stuck through the diagnosis flow.
- Run the full quality gates locally on the exact commit to be merged —
after the final rebase onto latest
origin/main. A pass on an older commit
does not count.
- Merge without waiting for checks, then leave a PR comment recording the
bypass: Actions status/incident observed, and that local gates passed
(with the commit SHA).
Do not use this fallback to route around a real CI failure — only when checks
cannot run or complete for infrastructure reasons.
