github-pr-merge — Claude Code skill: merge PRs after checks
github-pr-merge walks a pull request through the checks people skip, then merges it as a merge commit once you say go.
MIT 281 installs ★ 72 updated 2026-09-11
npx skills add fvadicamo/dev-agent-skills --skill github-pr-merge -a claude-codeWhat github-pr-merge does
The skill starts with review threads. If a top-level comment has no reply, it halts and points you to github-pr-review. Milestone comes next: a missing one raises a warning, never a block. Then gh pr checks, plus a diff against CHANGELOG.md — a feat, fix or perf commit with no changelog line stops the merge there.
Merging means a merge commit, always. Squash and rebase are not offered. Branch cleanup depends on direction: a topic branch heading into develop gets deleted, while develop into main keeps its head and no --delete-branch is passed. After the merge the skill switches to the base branch, pulls it, and counts what the milestone still holds open. Closing that milestone needs your confirmation.
All of it is a layer over the GitHub CLI. No gh install and login means no checks and no merge.
What it helps with
- confirm every review comment got a reply before merging
- gate the merge on tests, lint and CI
- catch behavior commits missing from the changelog
- merge with a merge commit and drop the spent branch
- close a milestone once its last issue lands
Example prompts for the agent
- Merge PR #42 if the checks are green
- Show the pre-merge checklist for the current PR
- Merge
developintomainwithout deleting the head branch
How to install github-pr-merge
1Skills CLI (Vercel)
npx skills add fvadicamo/dev-agent-skills --skill github-pr-merge -a claude-code2Manually: put the files in place
~/.claude/skills/github-pr-merge/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/github-pr-merge/
1Skills CLI (Vercel)
npx skills add fvadicamo/dev-agent-skills --skill github-pr-merge -a codex2Manually: put the files in place
.agents/skills/github-pr-merge/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add fvadicamo/dev-agent-skills --skill github-pr-merge -a cursor2Manually: put the files in place
.cursor/skills/github-pr-merge/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install fvadicamo/dev-agent-skills plugins/github-workflow/skills/github-pr-merge2Manually: put the files in place
.github/skills/github-pr-merge/SKILL.md1Skills CLI (Vercel)
npx skills add fvadicamo/dev-agent-skills --skill github-pr-merge -a gemini-cli2Platform CLI
gemini skills install https://github.com/fvadicamo/dev-agent-skills --path plugins/github-workflow/skills/github-pr-mergeManually: put the files in place
.devin/skills/github-pr-merge/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add fvadicamo/dev-agent-skills --skill github-pr-merge -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about github-pr-merge
How to install github-pr-merge in Claude Code?
Run npx skills add fvadicamo/dev-agent-skills --skill github-pr-merge -a claude-code. The skill lands at ~/.claude/skills/github-pr-merge/SKILL.md.
What does github-pr-merge do?
It runs the pre-merge checks on a pull request: comment replies, tests, lint, CI, milestone and changelog. Then it asks for confirmation, merges as a merge commit and syncs the base branch.
Does it squash pull requests?
No. Only --merge is used, never squash or rebase. Head branch deletion happens only when a topic branch goes into develop.
Source text
SKILL.md · MIT
---
name: github-pr-merge
description: Merges GitHub Pull Requests after validating pre-merge checklist. Use when user wants to merge PR, close PR, finalize PR, complete merge, approve and merge, or execute merge. Runs pre-merge validation (tests, lint, CI, comments), confirms with user, merges with proper format, handles post-merge cleanup.
---
# GitHub PR merge
Merges Pull Requests after validating pre-merge checklist and handling post-merge cleanup.
## Current PR
!`gh pr view --json number,title,state -q '"PR #\(.number): \(.title) (\(.state))"' 2>/dev/null`
## Core workflow
### 1. Check comments status
Verify all review comments have at least one reply:
```bash
REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')
PR=$(gh pr view --json number -q '.number')
# Find unreplied comment IDs
gh api repos/$REPO/pulls/$PR/comments --jq '
[.[] | select(.in_reply_to_id) | .in_reply_to_id] as $replied |
[.[] | select(.in_reply_to_id == null) | select(.id | IN($replied[]) | not) | .id]
'
```
**If unreplied comments exist:**
- **STOP** the merge process
- Inform user: "Found unreplied comments: [IDs]. Run github-pr-review first."
- **NEVER** reply to comments from this skill
### 2. Check milestone
```bash
gh pr view $PR --json milestone -q '.milestone.title // "none"'
```
- If milestone is assigned: include it in the checklist summary (step 5)
- If no milestone: check for open milestones and warn the user
```bash
gh api repos/$REPO/milestones --jq '[.[] | select(.state=="open")] | length'
```
If open milestones exist but the PR has none, surface a warning in the checklist:
`- Milestone: ⚠ not assigned (open milestones exist)`
Do NOT block the merge for a missing milestone. It is a warning only.
### 3. Run validation
Run tests, linting, and verify CI checks. All **MUST** pass before proceeding.
```bash
gh pr checks $PR
```
### 4. Verify changelog completeness
Skip if the repo has no `CHANGELOG.md`. Otherwise make sure every commit this merge will publish is reflected in the changelog, so a release-promotion merge (`develop` → `main`) never leaves commits unlogged.
List the commits this PR brings into the base, and the changelog lines it adds:
```bash
BASE=$(gh pr view $PR --json baseRefName -q .baseRefName)
HEAD=$(gh pr view $PR --json headRefName -q .headRefName)
git log --oneline origin/$BASE..origin/$HEAD
git diff origin/$BASE...origin/$HEAD -- CHANGELOG.md
```
- Every commit that changes shipped behavior (`feat`/`fix`/`perf`, behavior-affecting `refactor`) **MUST** have a matching changelog line; pure `chore`/`docs`/`test` commits that do not change shipped behavior may be omitted.
- For a release-promotion merge, also confirm the version was bumped (the top `## [x.y.z]` entry is new) and matches the manifest version(s).
- **If any behavior-changing commit is missing from the changelog: STOP.** Report the unlogged commits and ask the user to update the changelog and version before merging. **NEVER** edit the changelog from this skill.
### 5. Confirm with user
**ALWAYS show checklist summary and ask before merging:**
```
Pre-merge checklist:
- Comments: all replied
- Tests: passing
- Lint: passing
- CI: green
- Milestone: v0.1.0 (or ⚠ not assigned)
- Changelog: complete (or n/a)
Ready to merge PR #X. Proceed?
```
### 6. Execute merge
First determine the merge direction. It decides whether the head branch may be deleted:
```bash
gh pr view $PR --json baseRefName,headRefName -q '"\(.headRefName) -> \(.baseRefName)"'
```
**Branch deletion rule:**
- **Topic branch → `develop`** (head is a `feature`/`fix`/etc. branch): the branch is spent. Propose deleting it and merge with `--delete-branch`.
- **`develop` → `main`** (or any long-lived branch as head): **NEVER** delete the head branch. `develop` and `main` are permanent. Omit `--delete-branch` and do not propose deletion.
```bash
# Add --delete-branch ONLY for a topic branch merging into develop.
gh pr merge $PR --merge --delete-branch --body "$(cat <<'EOF'
- Key change 1
- Key change 2
- Key change 3
Reviews: N/N addressed
Tests: X passed (Y% cov)
Refs: Task N, Req M
EOF
)"
```
For a `develop` → `main` merge, run the same command **without** `--delete-branch`.
**Merge strategy**: always `--merge` (merge commit), never squash or rebase.
### 7. Post-merge cleanup
Sync the branch that received the merge (the PR base), not always `develop`:
```bash
BASE=$(gh pr view $PR --json baseRefName -q .baseRefName)
git checkout "$BASE" && git pull origin "$BASE"
```
### 8. Check milestone completion
If the PR had a milestone, check whether all items are now closed:
```bash
MILESTONE=$(gh pr view $PR --json milestone -q '.milestone.number // empty')
if [ -n "$MILESTONE" ]; then
gh api repos/$REPO/milestones/$MILESTONE \
--jq '"Open: \(.open_issues) | Closed: \(.closed_issues) | \(.title)"'
fi
```
- If `open_issues == 0`: inform the user and ask whether to close the milestone
```bash
gh api repos/$REPO/milestones/$MILESTONE --method PATCH --field state="closed"
```
- If `open_issues > 0`: report remaining open items count. No action needed.
- **NEVER** close a milestone automatically without explicit user confirmation.
## Merge message format
Concise format for a clean git log:
```
- Key change 1 (what was added/fixed)
- Key change 2
- Key change 3
Reviews: 7/7 addressed (Gemini 5, Codex 2)
Tests: 628 passed (88% cov)
Refs: Task 8, Req 14-15
```
- 3-5 bullet points max for changes
- One line each for reviews summary, test results, and task references
- No headers (##), no verbose sections
- Total: ~10 lines max
## Important rules
- **ALWAYS** run tests, lint, and CI checks before merging
- **ALWAYS** verify all review comments have replies
- **ALWAYS** check milestone assignment before merging (warn if missing, do not block)
- **ALWAYS** (repos with a CHANGELOG) verify it accounts for every behavior-changing commit this merge publishes; STOP and report any that are missing
- **ALWAYS** confirm with user before executing merge
- **ALWAYS** use merge commit (`--merge`), never squash/rebase
- **ALWAYS** delete the head branch only when merging a topic branch (`feature`/`fix`/etc.) into `develop`
- **NEVER** delete `develop` or `main`. On a `develop` → `main` merge, omit `--delete-branch` and never propose deletion
- **ALWAYS** check milestone completion after merge and report open items count
- **NEVER** merge with failing tests, lint, or CI checks
- **NEVER** skip user confirmation
- **NEVER** close a milestone without explicit user confirmation
- **NEVER** reply to PR comments from this skill - use github-pr-review instead
- **STOP** merge if unreplied comments exist and direct user to review skill
© fvadicamo · MIT · fvadicamo/dev-agent-skills