Merge PR

Overview

To merge a GitHub Pull Request safely, ensuring all CI checks pass, code review is completed, and no critical issues remain before proceeding. This skill provides a structured workflow for verifying CI status, performing code review, selecting merge strategies, and handling merge conflicts or failures.

Workflow

Step 1: Identify the PR

To identify which PR to merge:

1. If a PR number is provided, use it directly
2. If on a feature branch, find the associated PR:
   bashCopy

   gh pr view --json number,title,state,headRefName,baseRefName
   

3. If no PR exists for the current branch, inform the user and exit

Step 2: Verify CI Status

This step is mandatory and cannot be skipped.

To check all CI checks have passed:

gh pr checks <PR_NUMBER> --watch

Evaluate the result:

• All checks passed: Proceed to Step 3
• Some checks pending: Wait for completion using --watch flag
• Any check failed: Stop and report the failure. Do NOT proceed with merge.

Example failure report:

CI 检查未通过，无法合并 PR #123

失败的检查:
- build (failed): Build error in src/index.ts
- test (failed): 3 tests failed

请先修复这些问题后再尝试合并。

Step 3: Code Review

This step is mandatory and cannot be skipped.

To perform code review before merge, dispatch the superpowers:code-reviewer subagent.

3.1 Get Git SHAs

# Get the base branch (usually main or master)
BASE_BRANCH=$(gh pr view <PR_NUMBER> --json baseRefName -q '.baseRefName')
BASE_SHA=$(git rev-parse origin/$BASE_BRANCH)
HEAD_SHA=$(git rev-parse HEAD)

3.2 Dispatch Code Reviewer

Use the Task tool with superpowers:code-reviewer subagent type. Fill in the following template:

# Code Review Agent

You are reviewing code changes for production readiness.

**Your task:**
1. Review what was implemented in this PR
2. Compare against the PR description and requirements
3. Check code quality, architecture, testing
4. Categorize issues by severity
5. Assess production readiness

## What Was Implemented

{DESCRIPTION} - Brief summary of the PR changes

## Requirements/Plan

PR Title: {PR_TITLE}
PR Description: {PR_DESCRIPTION}

## Git Range to Review

**Base:** {BASE_SHA}
**Head:** {HEAD_SHA}

## Review Checklist

**Code Quality:**
- Clean separation of concerns?
- Proper error handling?
- Type safety (if applicable)?
- DRY principle followed?
- Edge cases handled?

**Architecture:**
- Sound design decisions?
- Scalability considerations?
- Performance implications?
- Security concerns?

**Testing:**
- Tests actually test logic (not mocks)?
- Edge cases covered?
- Integration tests where needed?
- All tests passing?

**Requirements:**
- All requirements met?
- Implementation matches spec?
- No scope creep?
- Breaking changes documented?

## Output Format

### Strengths
[What's well done? Be specific.]

### Issues

#### Critical (Must Fix)
[Bugs, security issues, data loss risks, broken functionality]

#### Important (Should Fix)
[Architecture problems, missing features, poor error handling, test gaps]

#### Minor (Nice to Have)
[Code style, optimization opportunities, documentation improvements]

### Assessment

**Ready to merge?** [Yes/No/With fixes]

**Reasoning:** [Technical assessment in 1-2 sentences]

3.3 Evaluate Review Results

Based on the code reviewer's assessment:

Example blocking report:

Code Review 未通过，无法合并 PR #123

发现以下问题需要修复:

Critical:
- [file:line] 问题描述

Important:
- [file:line] 问题描述

请先修复这些问题后再尝试合并。

Step 4: Check for Merge Conflicts

To verify the PR can be merged cleanly:

gh pr view <PR_NUMBER> --json mergeable,mergeStateStatus

Evaluate mergeable and mergeStateStatus:

• MERGEABLE + CLEAN: Proceed to Step 5
• CONFLICTING: Inform user about conflicts and provide resolution guidance
• BLOCKED: Check branch protection rules and report blockers

Step 5: Select Merge Strategy

To determine the merge method, check repository preferences or ask user:

Default to --squash if not specified, as it produces cleaner history.

Step 6: Execute Merge

To merge the PR:

gh pr merge <PR_NUMBER> --squash --delete-branch

Common flags:

• --delete-branch: Delete the head branch after merge (recommended)
• --auto: Enable auto-merge when checks pass (useful for pending checks)
• --body "message": Custom merge commit message

Step 7: Verify and Clean Up

After successful merge:

1. Confirm merge status:

   bashCopy

   gh pr view <PR_NUMBER> --json state,mergedAt,mergedBy
   

2. Update local repository:

   bashCopy

   git checkout main && git pull origin main
   

3. Clean up local branch if it still exists:

   bashCopy

   git branch -d <branch-name>
   

Error Handling

CI Check Failures

When CI checks fail, provide actionable feedback:

# Get detailed check information
gh pr checks <PR_NUMBER> --json name,state,conclusion,detailsUrl

Merge Conflicts

When conflicts are detected:

1. Report the conflicting files
2. Suggest resolution approach:
   bashCopy

   git checkout <feature-branch>
   git fetch origin main
   git merge origin/main
   # Resolve conflicts manually
   git add .
   git commit -m "Resolve merge conflicts"
   git push
   

Protected Branch Rules

When merge is blocked by branch protection:

gh pr view <PR_NUMBER> --json reviewDecision,reviews,statusCheckRollup

Report which requirements are not met (reviews, approvals, etc.).

Quick Reference

# Check CI status
gh pr checks <PR_NUMBER>

# Merge with squash (recommended)
gh pr merge <PR_NUMBER> --squash --delete-branch

# Enable auto-merge for pending checks
gh pr merge <PR_NUMBER> --squash --delete-branch --auto

# View PR details
gh pr view <PR_NUMBER> --json state,mergeable,mergeStateStatus,statusCheckRollup