merge-policy
The software-factory rule that main must always be green, and how to land PRs under it — when a bypass/admin merge is and is not allowed, how to handle a hung required check, and what to do when main
SKILL.md.claude/skills/merge-policy/SKILL.md
GitHubMerge policy: main must always be green
main must never carry a genuinely failing test, type error, or lint violation.
The rule
Never use gh pr merge --admin, or any merge that bypasses required status checks, to get past a check that is actually FAILURE. Fix the failure instead.
The only two legitimate bypasses
- The factory's own auto-merge. It bypasses the review-approval requirement, which a bot cannot obtain. Its CI gate (
waitForMergeinpackages/cli/src/cli/index.ts) still refuses to merge unless CI reported a realsuccess. It never merges on a failure or an unresolved or hung outcome. - A human confirms a required check is hung, not failed (for example the #739 CI deadlock). Before merging:
- Run
bash scripts/verify.sh --no-e2elocally and get it green. - Run targeted checks for anything the fast path skips (coverage:
npm run testthennpm run coverage-ratchet). - Say explicitly in the merge or PR comment that the check was hung and what you ran instead.
- Run
A bypass under case 2 is a workaround for an infra bug, not a norm. Open or link the issue that fixes the hang.
History: the multi-hour ci hang of #739/#755 was an unbounded microtask-only spin loop in router/index.test.ts, not the integration tests. CI jobs now carry a timeout-minutes ceiling so a future spin cannot strand open PRs.
When main is red
- Treat it as the top-priority task. A red
mainblocks every open PR, and every PR's diff is measured against it. - Reproduce on a fresh branch off
origin/mainwithbash scripts/verify.sh. - Fix the root cause in a small PR. Do not skip or delete the failing test to get green.
- Land the fix with normal required checks. Rebase other open PRs afterwards.
Landing a factory PR
factory shipandfactory run-issuestop at a ready-for-review PR. They never merge.factory land <issue>squash-merges a ready PR and cleans up its worktree.factory runmerges only when auto-merge is on (--auto-merge,.factory/config.yaml, orFACTORY_MERGE=1), and only through the CI gate above.