pr-merge-ci-gate

name	pr-merge-ci-gate
description	Use when checking CI status on a GitHub PR and deciding whether to merge — distinguishes blocking failures (GitHub Actions quality gates) from ignorable failures (Vercel preview deployments, sandbox Vercel builds). Triggers on "CI failing", "Vercel failing on PR", "can I merge", "pr merge blocked", "gh pr merge", or "check before merging".

PR Merge with CI Gate

Overview

Not all CI failures block a merge. Know the difference between required status checks (block merge) and optional checks (informational only) before deciding to wait or proceed.

---

Decision Flow

digraph merge_decision {
  "Check PR status" [shape=box];
  "Any required check failing?" [shape=diamond];
  "Failing check type?" [shape=diamond];
  "Wait / fix" [shape=box];
  "Safe to merge" [shape=box];
  "Vercel preview build" [shape=box];
  "GitHub Actions workflow" [shape=box];
  "Merge — preview failures ignorable" [shape=box];
  "Fix workflow before merging" [shape=box];

  "Check PR status" -> "Any required check failing?";
  "Any required check failing?" -> "Failing check type?" [label="yes"];
  "Any required check failing?" -> "Safe to merge" [label="no"];
  "Failing check type?" -> "Vercel preview build" [label="Vercel"];
  "Failing check type?" -> "GitHub Actions workflow" [label="GH Actions"];
  "Vercel preview build" -> "Merge — preview failures ignorable";
  "GitHub Actions workflow" -> "Fix workflow before merging";
}

---

Step 1 — Check Status

gh pr view <number> --json mergeable,statusCheckRollup

Parse the output:

• mergeable: "MERGEABLE" — no git conflicts
• mergeable: "CONFLICTING" — resolve conflicts first (see conflict resolution below)
• statusCheckRollup — list of check names + state/conclusion

---

Step 2 — Classify Failures

Check name pattern	Type	Block merge?
Quality Checks (GitHub Actions)	Required	Yes — fix first
Vercel – <project-name>	Vercel preview	No — ignorable
Vercel – <project-name>-sandbox	Vercel preview	No — ignorable
Vercel Preview Comments	Vercel bot	No — informational
CodeRabbit	Code review bot	No — advisory
Custom workflow names	Check branch protection rules	Varies

Why Vercel previews fail on feature branches:

• Environment variables not set for the preview environment
• Preview projects use different configs
• Binary assets (large .mp4 files) that Vercel doesn't handle in preview
• Pre-existing build errors in the repo unrelated to this PR

When to treat Vercel failures as blocking:

• The same Vercel project builds green on main but fails here → investigate
• Failure message mentions a specific file you changed → investigate
• PR is for a Vercel-deployed feature that needs preview verification

---

Step 3 — Merge Command

# Squash merge (preferred for feature branches)
gh pr merge <number> --squash \
  --subject "feat: descriptive title under 70 chars" \
  --body "$(cat <<'EOF'
## Summary
- bullet 1
- bullet 2

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

# Standard merge (preserves commits)
gh pr merge <number> --merge

# Merge despite non-required failing checks (use with caution)
gh pr merge <number> --squash --auto   # waits for required checks, ignores optional

---

Conflict Resolution (when mergeable: "CONFLICTING")

# In the feature branch worktree
git fetch origin
git merge origin/main --no-edit

# Check what actually conflicts
git diff --name-only --diff-filter=U

# Common safe resolutions:
# - Accept main's version for files the branch touched but main has since updated
git checkout --theirs <file>
git add <file>

# - Accept branch's version for files unique to this feature
git checkout --ours <file>
git add <file>

# Commit and push
git commit -m "merge(main): resolve conflicts"
git push origin <branch>

Key principle: If a file was independently updated on both branches, default to --theirs (main) for infrastructure files (package.json, pnpm-lock.yaml, prisma/schema.prisma, config files). Use --ours only for feature files that main didn't touch.

---

Quick Reference

# 1. Check status
gh pr view 148 --json mergeable,statusCheckRollup | \
  python3 -c "import json,sys; d=json.load(sys.stdin); \
  print('Mergeable:', d['mergeable']); \
  [print(c.get('context') or c.get('name'), '->', c.get('state') or c.get('conclusion')) \
   for c in d['statusCheckRollup']]"

# 2. Merge if Quality Checks pass (even if Vercel previews fail)
gh pr merge 148 --squash --subject "fix(seo): your title here"

# 3. Verify merge
gh pr view 148 --json state,mergedAt

---

Common Mistakes

Mistake	Fix
Waiting for Vercel previews to go green	They may never go green on feature branches — check if they're required
Merging with CONFLICTING state	Resolve conflicts first — the merge will fail or produce bad output
Using --admin to force-merge past required checks	Fix the required checks instead
Assuming all checks are equal	Read the branch protection rules or check which checks are listed as "Required" in the PR UI