merge-pr

sakuro's avatarfrom sakuro

Safely merges GitHub pull requests using gh CLI. Use when the user wants to merge a PR, merge a pull request, or complete code review.

⭐2stars🔀0forks📁View on GitHub🕐Updated Jan 3, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill automates the GitHub pull request merge process using the gh CLI, ensuring all CI checks and code reviews are satisfied before integration. It solves the problem of manual verification fatigue and inconsistent merge strategies, providing a safe, standardized workflow that maintains repository integrity and synchronizes local environments.

Use Cases

  • Verifying CI/CD pipeline status and reviewer approvals to ensure a pull request meets all safety requirements before merging into the production branch.
  • Executing squash merges to maintain a clean project history by consolidating multiple work-in-progress commits into a single, descriptive commit.
  • Automating post-merge cleanup by switching to the default branch, pulling the latest changes, and deleting merged local branches to keep the workspace tidy.
  • Configuring auto-merge for pull requests to streamline the development workflow when waiting for long-running automated tests to complete.
namemerge-pr
descriptionSafely merges GitHub pull requests using gh CLI. Use when the user wants to merge a PR, merge a pull request, or complete code review.
allowed-tools[Bash, Read, Grep]

Merge PR Skill

Assists with safely merging GitHub pull requests using the gh CLI, following best practices for code review, CI checks, and merge strategies.

IMPORTANT: When using this skill, announce to the user: "Using merge-pr skill to merge a pull request safely."

Instructions

1. Pre-Merge Checks

ALWAYS verify the following before merging:

# View PR details, status checks, and reviews
gh pr view [PR_NUMBER]

# Check CI status
gh pr checks [PR_NUMBER]

# View PR diff (optional, for review)
gh pr diff [PR_NUMBER]

Required conditions before merging:

  • ✅ All required CI checks must pass
  • ✅ Required approvals must be met (check branch protection rules)
  • ✅ No unresolved review comments or change requests
  • ⚠️ Confirm you have permission to merge

If checks fail:

  • Wait for CI to complete
  • Address review feedback
  • Fix failing tests
  • Re-run checks if needed: gh pr checks --watch [PR_NUMBER]

2. Merge Strategy Selection

Default: Merge Commit (--merge)

  • Preserves all commits from the PR branch
  • Creates a merge commit
  • Maintains complete history
  • ALWAYS specify merge commit subject in this format: :inbox_tray: Merge pull request #[PR_NUMBER] from [BRANCH_NAME]
# Get PR branch name with owner (e.g., "owner/branch-name")
BRANCH_NAME=$(gh pr view [PR_NUMBER] --json headRepositoryOwner,headRefName -q '.headRepositoryOwner.login + "/" + .headRefName')

# Merge with custom subject
gh pr merge [PR_NUMBER] --merge --subject ":inbox_tray: Merge pull request #[PR_NUMBER] from $BRANCH_NAME"

Alternative strategies (use only when appropriate):

Squash Merge (--squash)

  • Combines all commits into a single commit
  • Use when: PR has many small/WIP commits that should be consolidated
gh pr merge [PR_NUMBER] --squash

Rebase Merge (--rebase)

  • Replays commits from PR branch onto base branch
  • Use when: Small PRs with clean commits, want linear history without merge commit
gh pr merge [PR_NUMBER] --rebase

3. Branch Deletion

Branch deletion is handled by GitHub repository settings:

  • Repository settings → "Automatically delete head branches"
  • If enabled, branches are deleted automatically after merge
  • If disabled, branches remain for manual cleanup
  • Do NOT use --delete-branch flag - respect the repository configuration

4. Post-Merge Local Update

After merging a PR, ALWAYS update your local default branch:

# 1. Get the repository's default branch name
DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name)

# 2. Switch to the default branch
git checkout "$DEFAULT_BRANCH"

# 3. Pull the latest changes (including the merge)
git pull

# 4. (Optional) Clean up local merged branches
git branch --merged | grep -v "\*" | grep -v "$DEFAULT_BRANCH" | xargs -n 1 git branch -d

Alternative (if you know the default branch name):

# If you know it's 'main'
git checkout main && git pull

# If you know it's 'master'
git checkout master && git pull

5. Complete Merge Workflow

Follow this sequence:

# 1. Check PR status and reviews
gh pr view [PR_NUMBER]

# 2. Verify all checks pass
gh pr checks [PR_NUMBER]

# 3. Get PR branch name with owner for merge commit subject
BRANCH_NAME=$(gh pr view [PR_NUMBER] --json headRepositoryOwner,headRefName -q '.headRepositoryOwner.login + "/" + .headRefName')

# 4. Merge with default strategy (merge commit) and custom subject
gh pr merge [PR_NUMBER] --merge --subject ":inbox_tray: Merge pull request #[PR_NUMBER] from $BRANCH_NAME"

# 5. Verify merge completed
gh pr view [PR_NUMBER]
# Should show status: MERGED

# 6. Update local repository
DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name)
git checkout "$DEFAULT_BRANCH"
git pull

# 7. (Optional) Clean up local merged branches
git branch --merged | grep -v "\*" | grep -v "$DEFAULT_BRANCH" | xargs -n 1 git branch -d

6. Safety Guidelines

NEVER merge if:

  • ❌ CI checks are failing
  • ❌ There are unresolved change requests from reviewers
  • ❌ You don't have proper permissions
  • ❌ The PR targets the wrong base branch
  • ❌ Required approvals are missing

ALWAYS:

  • ✅ Read PR description and understand what's being merged
  • ✅ Verify CI passes completely
  • ✅ Check that required reviews are approved
  • ✅ Use --merge (default strategy) to preserve commit history
  • ✅ Specify merge commit subject as :inbox_tray: Merge pull request #[PR_NUMBER] from [BRANCH_NAME]
  • ✅ Update local default branch after merging
  • ✅ Let GitHub repository settings handle branch deletion

7. Common gh pr merge Options

# Basic merge commit (DEFAULT) - with custom subject
BRANCH_NAME=$(gh pr view [PR_NUMBER] --json headRepositoryOwner,headRefName -q '.headRepositoryOwner.login + "/" + .headRefName')
gh pr merge [PR_NUMBER] --merge --subject ":inbox_tray: Merge pull request #[PR_NUMBER] from $BRANCH_NAME"

# Squash merge (only when needed)
gh pr merge [PR_NUMBER] --squash

# Rebase merge (only when needed)
gh pr merge [PR_NUMBER] --rebase

# Auto-merge (merge when checks pass) - with custom subject
BRANCH_NAME=$(gh pr view [PR_NUMBER] --json headRepositoryOwner,headRefName -q '.headRepositoryOwner.login + "/" + .headRefName')
gh pr merge [PR_NUMBER] --auto --merge --subject ":inbox_tray: Merge pull request #[PR_NUMBER] from $BRANCH_NAME"

# Merge current branch's PR
BRANCH_NAME=$(gh pr view --json headRepositoryOwner,headRefName -q '.headRepositoryOwner.login + "/" + .headRefName')
gh pr merge --merge --subject ":inbox_tray: Merge pull request #[PR_NUMBER] from $BRANCH_NAME"

# Disable auto-merge
gh pr merge [PR_NUMBER] --disable-auto

8. Working with the Current Branch

If you're on a branch with an open PR:

# Get current PR number and branch name
PR_NUMBER=$(gh pr view --json number -q .number)
BRANCH_NAME=$(gh pr view --json headRepositoryOwner,headRefName -q '.headRepositoryOwner.login + "/" + .headRefName')

# Merge the PR for current branch
gh pr merge --merge --subject ":inbox_tray: Merge pull request #$PR_NUMBER from $BRANCH_NAME"

# Check PR status for current branch
gh pr status

# View current branch's PR
gh pr view

Examples

Example 1: Standard Merge with Merge Commit (Default)

# Check PR status
gh pr view 42

# Verify checks pass
gh pr checks 42

# Get branch name and merge with custom subject
BRANCH_NAME=$(gh pr view 42 --json headRepositoryOwner,headRefName -q '.headRepositoryOwner.login + "/" + .headRefName')
gh pr merge 42 --merge --subject ":inbox_tray: Merge pull request #42 from $BRANCH_NAME"

# Update local default branch
DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name)
git checkout "$DEFAULT_BRANCH"
git pull

Example 2: Complete Workflow with Cleanup

gh pr view 42
gh pr checks 42

# Get branch name and merge
BRANCH_NAME=$(gh pr view 42 --json headRepositoryOwner,headRefName -q '.headRepositoryOwner.login + "/" + .headRefName')
gh pr merge 42 --merge --subject ":inbox_tray: Merge pull request #42 from $BRANCH_NAME"

# Update and clean up
DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name)
git checkout "$DEFAULT_BRANCH"
git pull
git branch --merged | grep -v "\*" | grep -v "$DEFAULT_BRANCH" | xargs -n 1 git branch -d

Example 3: Auto-merge with Local Update

# Get branch name and set PR to auto-merge when checks pass
BRANCH_NAME=$(gh pr view 99 --json headRepositoryOwner,headRefName -q '.headRepositoryOwner.login + "/" + .headRefName')
gh pr merge 99 --auto --merge --subject ":inbox_tray: Merge pull request #99 from $BRANCH_NAME"

# Wait for merge, then update
gh pr view 99  # Check if merged

DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name)
git checkout "$DEFAULT_BRANCH"
git pull

Example 4: Merge Current Branch

# When you're on the PR branch
gh pr view  # Verify it's the right PR

# Get PR number and branch name
PR_NUMBER=$(gh pr view --json number -q .number)
BRANCH_NAME=$(gh pr view --json headRepositoryOwner,headRefName -q '.headRepositoryOwner.login + "/" + .headRefName')
gh pr merge --merge --subject ":inbox_tray: Merge pull request #$PR_NUMBER from $BRANCH_NAME"

# Update default branch
DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name)
git checkout "$DEFAULT_BRANCH"
git pull

Common Pitfalls to Avoid

  1. Don't merge with failing checks: Always verify gh pr checks passes
  2. Don't specify branch deletion: Let GitHub settings handle it
  3. Don't merge without reviews: Check that required approvals are present
  4. Don't merge to wrong branch: Verify base branch in gh pr view
  5. Don't forget to update local: Always pull the default branch after merging
  6. Don't hardcode branch name: Use gh repo view --json defaultBranchRef to get the correct default branch
  7. Don't use squash by default: Use --merge to preserve commit history
  8. Don't forget merge commit subject: Always use :inbox_tray: Merge pull request #[PR_NUMBER] from [BRANCH_NAME] format

Error Recovery

If merge fails due to conflicts:

# PR cannot be merged automatically
# You need to resolve conflicts first

# Update branch with base
gh pr checkout [PR_NUMBER]
git fetch origin
DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name)
git merge "origin/$DEFAULT_BRANCH"
# Resolve conflicts
git push

# Then retry merge with custom subject
BRANCH_NAME=$(gh pr view [PR_NUMBER] --json headRepositoryOwner,headRefName -q '.headRepositoryOwner.login + "/" + .headRefName')
gh pr merge [PR_NUMBER] --merge --subject ":inbox_tray: Merge pull request #[PR_NUMBER] from $BRANCH_NAME"

If accidentally merged wrong PR:

# Revert the merge commit
DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name)
git checkout "$DEFAULT_BRANCH"
git pull
git log  # Find the merge commit hash
git revert -m 1 [MERGE_COMMIT_HASH]
git push

If local update fails:

# Check current branch
git branch

# Ensure you're on the default branch
DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name)
git checkout "$DEFAULT_BRANCH"

# If you have uncommitted changes
git stash
git pull
git stash pop

Advanced Usage

Check repository default branch:

# Get default branch name
gh repo view --json defaultBranchRef -q .defaultBranchRef.name

# Get full default branch info
gh repo view --json defaultBranchRef

Check if PR is ready to merge:

# View detailed status
gh pr view [PR_NUMBER] --json statusCheckRollup,reviewDecision

# Watch checks until they complete
gh pr checks [PR_NUMBER] --watch

Merge multiple PRs:

# Use a loop (be careful!)
for pr in 42 43 44; do
  if gh pr checks $pr; then
    BRANCH_NAME=$(gh pr view $pr --json headRepositoryOwner,headRefName -q '.headRepositoryOwner.login + "/" + .headRefName')
    gh pr merge $pr --merge --subject ":inbox_tray: Merge pull request #$pr from $BRANCH_NAME"
  fi
done

# Update local once after all merges
DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name)
git checkout "$DEFAULT_BRANCH"
git pull

Query mergeable state:

# Check if PR can be merged
gh pr view [PR_NUMBER] --json mergeable,mergeStateStatus

Project-Specific Conventions

Always check if the project has specific merge requirements:

  • Read CONTRIBUTING.md for merge strategy preferences
  • Check branch protection rules on GitHub
  • Follow team conventions for commit messages
  • Respect required reviewers and approvals
  • Default to --merge unless project specifies otherwise
  • Branch deletion is controlled by repository settings, not by this skill
  • Use gh repo view --json defaultBranchRef to detect the default branch dynamically
  • Merge commit subject format: Always use :inbox_tray: Merge pull request #[PR_NUMBER] from [BRANCH_NAME]