← ClaudeAtlas

gh-pr-merge-unstable-state-needs-auto-and-watch-branch-deleteslisted

Diagnose and recover from two adjacent `gh pr merge` failure modes that masquerade as merge conflicts. Use when: (1) `gh pr merge --squash` (or `--merge`) errors with "To have the pull request merged after all the requirements have been met, add the `--auto` flag" AND "Run the following to resolve the merge conflicts locally" even though you just pushed a clean resolution; (2) `gh pr view <N> --json mergeable,mergeStateStatus` returns `MERGEABLE` + `UNSTABLE` rather than `MERGEABLE` + `CLEAN`; (3) you delete the remote branch (`git push origin --delete <branch>`) immediately after `gh pr merge` returns a conflict warning thinking the merge succeeded — and discover the PR has flipped to `CLOSED` rather than `MERGED`. The actual root cause for (1)/(2) is almost always pending CI / branch-protection checks, NOT real merge conflicts; the fix is `--auto` flag so `gh` queues the merge for when checks pass. For (3) — recovery requires restoring the remote branch (`git push -u origin <branch>` from your local copy) a
wan-huiyan/agent-traffic-control · ★ 2 · Code & Development · score 79
Install: claude install-skill wan-huiyan/agent-traffic-control
# `gh pr merge` UNSTABLE state + branch-delete recovery ## Problem Two adjacent failure modes that read as "merge conflicts" but aren't: ### Failure A: `gh pr merge` rejects with "conflicts" when there are none You push a clean resolution of merge conflicts, GitHub shows the PR as MERGEABLE, and yet: ``` $ gh pr merge 915 --squash To have the pull request merged after all the requirements have been met, add the `--auto` flag. Run the following to resolve the merge conflicts locally: gh pr checkout 915 && git fetch origin main && git merge origin/main ``` The first line is the actual hint; the second is misleading boilerplate. The real cause is `mergeStateStatus: UNSTABLE` — branch protection or CI checks are pending. `gh` can't merge yet because the repo's rules aren't satisfied, not because of file-level conflicts. ### Failure B: PR auto-closes if you delete the remote branch right after Failure A Common pattern: previous PR on the same branch merged cleanly with `gh pr merge <N> --squash`. You then do `git push origin --delete <branch>` to clean up. Habit kicks in for the next PR — you run `gh pr merge` (gets Failure A above), notice the "conflicts" warning, run `git push origin --delete <branch>` anyway thinking the merge already landed remotely... ``` $ gh pr view 915 --json state {"state":"CLOSED"} # ← not MERGED — the PR closed because the branch was deleted with the merge un-queued ``` GitHub treats a deleted-branch PR with no merge in progress as abandon