| name | mergeable-please |
| description | Drive a GitHub pull request toward mergeable. Run when asked to "make a PR mergeable", "loop until the PR is ready", "fix the PR until CI/conflicts/reviews pass", or similar. Repeatedly runs `mergeable-please check`, resolves each reported blocker (conflicts, behind-base, failing/pending required CI, reviewer-loop goals), and loops until the tool reports satisfied. |
| license | MIT |
| compatibility | ["claude","codex","agents"] |
| allowed_tools | ["Bash","Read"] |
mergeable-please
Loop a GitHub pull request to merge-readiness. mergeable-please is a stateless,
single-shot CLI: it diagnoses every merge condition the agent can act on and
tells you the next action. You drive the loop by re-running it after each fix.
The loop
- Run
mergeable-please check (add the PR number or URL if you are not on the
PR's branch, e.g. mergeable-please check 42).
check prints a task list. The first line is the header
status: satisfied|blocked · owner/repo#n <url>; then one checkbox per merge
condition and reviewer. Each item may carry indented supplements: a status
line (e.g. rally 3/5 · goal approved) and a → action naming the next move
and, after ·, the one view/request subcommand for depth. Trailing ~
lines are human-only notes. Read the exit code and header:
- exit
0 / status: satisfied → stop. Every - [x] is done; only
human-gated ~ advisories (if any) remain.
- exit
1 / status: blocked → the - [ ] items are outstanding. Work them
top-down, following each item's indented → action, then go back to step 1.
- exit
2 → a usage/config/API error. Read the message and fix the invocation
(do not loop on this).
- For depth on any item, run the subcommand from its
→ action (e.g.
mergeable-please view --condition checks|conflicts|rules|reviewers) — check
itself stays terse. Resolve each outstanding - [ ] item by its kind, then go
back to step 1:
conflict → merge or rebase the base branch, resolve conflicts, commit, push.behind-base → the repo enforces up-to-date branches. Rebase onto the base
and push (git fetch && git rebase origin/<base> && git push --force-with-lease).check-failing → run mergeable-please view --condition checks to see which
required checks failed, investigate the root cause, fix it, push.check-pending → required checks are still running. Wait, then re-run check.merge-eligibility-pending → GitHub is still computing the merge state. Wait
15–30 seconds and re-run check.- reviewer
N unresolved → resolve those conversations first
(mergeable-please view --condition reviewers shows them), push, then
(re)request with mergeable-please request --reviewer <type:name>.
Re-requests are blocked until the head advances, so always push your fix
first. After (re)requesting, the reviewer needs time to respond — poll in a
background shell (e.g. run sleep 60 && mergeable-please check as a
background job, never in the foreground) so you are not blocked.
- reviewer
changes requested → the reviewer formally requested changes. Read
the review body and any threads (view --condition reviewers), address the
feedback, push, then re-request. If you genuinely cannot address the request
(e.g. it asks for a change you should not make) and no new commit is
possible, stop and escalate to the human — the tool will keep reporting
blocked, which is correct, and you must not loop. The item's → action says
exactly this when it applies.
- reviewer
awaiting review → no outstanding request; (re)request and poll in
the background as above.
- The trailing
~ lines are NOT blockers and never prevent satisfied:
~ approval required (human) / ~ ruleset block … → require a human or
out-of-scope action. Report them as remaining follow-ups; do not try to
satisfy them yourself.~ review notes present … → a reviewer left a review body that may contain
findings not tied to any inline thread (e.g. CodeRabbit "outside diff range"
comments). Read it with mergeable-please view --condition reviewers.~ … exhausted … → a reviewer used all its rallies without meeting its
goal; stop the loop for it or raise max-rallies.
Notes
- Prefer the exit code as the stop signal; the
status: line is the human/agent
mirror of it.
- Reviewer quality loops are opt-in via
.mergeable-please.yml at the repo root.
With no config file, check evaluates conflicts and ruleset/CI only.
- After pushing a fix, give CI a moment before re-running
check.
