github-pr-merge

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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.

From fvadicamo/dev-agent-skills, MIT.

More from fvadicamo/dev-agent-skills