safe-merge
Skill2 starsChanged 23 days agoMITView on GitHub
Merge a GitHub pull request without closing the pull requests stacked on it, by merging without branch deletion and deleting the head branch only if no open PR uses it as its base. Use whenever a PR is to be merged with gh, when the merge guard denied a gh pr merge, or when the user says 'merge PR', 'merge this', 'land it', 'merge the stack'.
In this repository38 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- arenaSkill
- codebase-oracleSkill
- geppettoSkill
- lean-subagent-devSkill
- methodologySkill
- overnight-runSkill
- parallel-worktreesSkill
- dependency-security-auditSkill
- dependency-upgradeSkill
- rule-to-hookSkill
- agent-friendly-auditSkill
- architectSkill
- brainstormSkill
- engineering-principlesSkill
- grill-meSkill
- improve-codebase-architectureSkill
- sharpenSkill
- to-issuesSkill
- to-prdSkill
- handoffSkill
- instructions-auditSkill
- project-setupSkill
- retrospectiveSkill
- session-closeSkill
- which-skillSkill
- bug-fixSkill
- ci-cost-and-cadenceSkill
- evaluatorSkill
- flaky-test-huntSkill
- hillclimbSkill
- launch-readinessSkill
- migration-reviewSkill
- mutation-testSkill
- review-triageSkill
- skill-evalSkill
- tddSkill
- verify-appSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
Always run the dry run first and show its output to the user.
- Very specific: line 74
When B is based on A's branch: merge A with this script (A's branch survives because B uses it), then gh pr edit <B> --base <trunk>, bring …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Safe merge
gh pr merge is denied by this plugin's merge guard. Merge with the script instead:
node "${CLAUDE_SKILL_DIR}/safe-merge.mjs" <number> --dry-run # reads only: prints what it would do
node "${CLAUDE_SKILL_DIR}/safe-merge.mjs" <number>Always run the dry run first and show its output to the user. Merging is an outward-facing action: get the user's go ahead for this specific PR before the real run, unless they already gave it for this PR.
Before merging on an older verdict
A verdict here is an approving human review, or a run of the evaluator skill if it is installed, given at an earlier
commit than the current head. A passing CI run or a bot's approval is not one to carry over: CI must pass at the
current head. A verdict covers a patch, not a commit, so after a rebase, a force-push or the trunk merged into the
branch, compare patch ids. Fetch first (git fetch origin, and for a PR from a fork also
git fetch origin pull/<number>/head); the patch id of <sha> against <base> is the first field of:
B=$(git merge-base <base> <sha>); git -c core.quotePath=true diff-tree -p --full-index "$B" <sha> | git patch-id --verbatimgit diff-tree ignores the user's diff settings and the two options pin how paths and binary files are written, so
the id does not depend on local configuration. Only --verbatim keeps whitespace (the default and --stable strip
it), so an indentation change that alters what Python code does changes the id. If git does not know --verbatim,
treat the verdict as stale.
- The verdict's id is the one recorded with it, with its base (the evaluator prints both on its
Evaluated:line). An evaluator verdict with no id (for examplepatch id not computed: uncommitted changes) is not reused. A human review records none: compute it from the review's commit (commit_idingh api repos/{owner}/{repo}/pulls/<n>/reviews, a REST call;gh pr viewuses GraphQL and may fail) against the PR's base at that time (for a stacked PR, the branch of the PR below it). A recorded id stands even if its SHA is gone; recompute it with the recorded base only to confirm it. No recorded id and no old SHA: the verdict is stale. - The current id:
<base>isorigin/<base>from the dry run'sPR #<n>: <head> -> <base>line (a dry run refused as stacked, draft or closed prints it too; for a promotion PR it is the target, not the trunk), ororigin/<default branch>for a branch with no PR yet.<sha>isgit rev-parse origin/<head>after the fetch (for a fork,git rev-parse FETCH_HEADright after fetchingpull/<number>/head); if it differs from the SHA after--match-head-commitin the dry run'sWould run:line, someone pushed: run the dry run again. - Same id: the verdict holds. Different id: the verdict is stale; see what changed with
git range-diff <old base>...<old sha> <base>...<sha>(or diff the two patches), then redo the review or the evaluation at the current head before merging. An empty current id (a SHA that is not there, or no diff at all) means not checked, never a match.
The id stays the same across a rebase onto unrelated commits or one that shifts line numbers, the trunk merged into the branch, a message-only amend and squashing the branch's commits. It changes on any edit to the change, and also when a trunk edit lands within 3 lines of a hunk, because context lines are hashed; that errs toward stale.
What the script checks
- The repository and the active gh account (printed; refused if
SAFE_MERGE_REPOis set and differs). - The PR is open, not a draft, and its base is the trunk (the repository's default branch, or
SAFE_MERGE_TRUNK), or one of the head->base pairs inSAFE_MERGE_PROMOTIONS(for exampledevelop->main). A PR based on another PR's branch is refused with the steps to retarget it. - It merges pinned to the head commit it read (
--match-head-commit), so a push in between cannot slip in. - Afterwards it deletes the remote head branch only if no open PR uses it as its base, it is not protected, and the PR does not come from a fork. Otherwise it prints the next step for each stacked PR.
Exit codes
0 done; 1 the merge failed (nothing deleted); 2 usage; 3 refused before merging; 4 merged, but the branch could not be
deleted or the decision could not be made. The output always contains a MERGED: yes or MERGED: no line; never
re-run a merge after MERGED: yes.
Stacked PRs, in one paragraph
When B is based on A's branch: merge A with this script (A's branch survives because B uses it), then
gh pr edit <B> --base <trunk>, bring the trunk into B's branch, and close and reopen B so CI runs (retargeting does
not trigger it). When B merges, A's branch is no longer anyone's base and the next merge deletes it.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

