Backport PR

Backport PR Skill

Purpose: Given an existing GitHub Pull Request number, cherry-pick its commit(s) onto a target branch (e.g. release/5.x, maintenance/4.x) and open a new backport PR referencing the original.

When to use:

• Porting a merged fix/feature from main to a release branch
• Re-applying a patch from one long-lived branch onto another
• User mentions "backport", "cherry-pick PR", or "port fix to <branch>"

Prerequisites

Before starting, verify:

1. gh CLI installed and authenticated:

   gh auth status

2. Current repo is a valid git clone with origin pointing at the GitHub repo.
3. Working tree is clean (no uncommitted changes).
4. You have push access to the origin remote (needed to open the backport PR).

If any check fails, stop and report the issue to the user before proceeding.

Inputs

The skill takes one required input:

• PR number — the numeric GitHub PR being backported (e.g. 1234).

Accept it from the invocation argument or prompt for it:

Enter the PR number to backport:

The target branch is always prompted (see Step 4).

Workflow

Copy this checklist and track progress:

Backport Progress:
- [ ] Step 1: Validate environment
- [ ] Step 2: Fetch PR metadata
- [ ] Step 3: Determine commits to cherry-pick (merge strategy)
- [ ] Step 4: Prompt for target branch
- [ ] Step 5: Create backport branch
- [ ] Step 6: Cherry-pick commit(s)
- [ ] Step 7: Push backport branch
- [ ] Step 8: Open backport PR
- [ ] Step 9: Final summary

Step 1: Validate Environment

gh auth status
git rev-parse --is-inside-work-tree
git status --short

• If gh auth status fails → tell the user to run gh auth login and stop.
• If git status --short shows any output → ask the user to commit or stash first and stop.

Also capture the remote repo slug for later PR operations:

gh repo view --json nameWithOwner -q .nameWithOwner

Step 2: Fetch PR Metadata

gh pr view <pr-number> --json number,title,state,mergedAt,mergeCommit,commits,baseRefName,headRefName,url,author

Extract and store:

• number → $PR_NUMBER
• title → $PR_TITLE
• state → must be MERGED (warn if not; allow override)
• mergeCommit.oid → $MERGE_SHA (null indicates a rebase-merged PR; present for squash or merge-commit)
• commits[*].oid → $PR_COMMITS (ordered list)
• baseRefName → $ORIGINAL_BASE (usually main)
• headRefName → $ORIGINAL_HEAD (original source branch)
• url → $PR_URL

Display a short summary to the user:

PR #<number>: <title>
  Author:      <author.login>
  State:       <state>
  Base:        <baseRefName>
  Head:        <headRefName>
  Commits:     <len(commits)>
  Merge SHA:   <mergeCommit.oid or "none (likely rebase-merged)">

If state is not MERGED, ask:

This PR is not yet merged. Backport anyway? (yes/no)

Step 3: Determine Commits to Cherry-Pick (Auto-Detect Merge Strategy)

Fetch the latest refs first:

git fetch origin --tags

Auto-detect which commit(s) to cherry-pick based on how the PR was merged:

1. Squash merge — mergeCommit.oid points to a commit on $ORIGINAL_BASE whose parent count is 1 AND whose commit message typically contains (#<pr-number>). Check with:

   git cat-file -p <MERGE_SHA> | head -20
   # parents count:
   git rev-list --parents -n 1 <MERGE_SHA> | awk '{print NF-1}'

   • Parent count 1 → squash. Cherry-pick strategy: git cherry-pick <MERGE_SHA>.
   • Store: CP_MODE=squash, CP_ARGS="<MERGE_SHA>".

2. Merge commit — mergeCommit.oid has 2 parents.

   • Cherry-pick strategy: git cherry-pick -m 1 <MERGE_SHA>.
   • Store: CP_MODE=merge, CP_ARGS="-m 1 <MERGE_SHA>".

3. Rebase merge — mergeCommit.oid is null OR the commits appear individually on $ORIGINAL_BASE (no merge/squash commit). Also falls here if PR is not merged yet.

   • Cherry-pick strategy: cherry-pick every SHA in $PR_COMMITS in order.
   • Store: CP_MODE=rebase, CP_ARGS="<sha1> <sha2> ...".

Always confirm the detected plan with the user before proceeding:

Detected merge strategy: <CP_MODE>
Will cherry-pick: <CP_ARGS>

Proceed? (yes/no/override)

If override, offer the three modes explicitly and let the user pick.

Step 4: Prompt for Target Branch

Ask the user (always — do not guess):

Enter the target branch to backport into (e.g. release/5.x, maintenance/4.x):

Store as $TARGET_BRANCH.

Verify the target exists on origin:

git ls-remote --heads origin <TARGET_BRANCH>

If empty → error out with: Target branch '<TARGET_BRANCH>' not found on origin.

Fetch the target:

git fetch origin <TARGET_BRANCH>

Step 5: Create Backport Branch

Compute branch name: backport/<target-sanitized>/pr-<pr-number>

Where <target-sanitized> replaces / with - (e.g. release/5.x → release-5.x).

Examples:

• Target release/5.x, PR 1234 → backport/release-5.x/pr-1234
• Target maintenance/4.x, PR 987 → backport/maintenance-4.x/pr-987

Show the user:

Backport branch name: backport/<target-sanitized>/pr-<pr-number>

Accept this name or provide an override? (accept/override)

Create the branch from the target:

git checkout -b backport/<target-sanitized>/pr-<pr-number> origin/<TARGET_BRANCH>

If the local branch already exists → ask:

Branch already exists. (delete-and-recreate/use-existing/abort)

Step 6: Cherry-Pick Commit(s)

Execute according to CP_MODE:

squash / merge:

git cherry-pick $CP_ARGS

rebase (multiple commits): iterate in order:

git cherry-pick <sha1>
git cherry-pick <sha2>
...

For each cherry-pick, check exit code:

• Success (exit 0) → continue to next commit (if any).

• Conflict (exit non-zero) → pause and prompt the user:

  ⚠️ Cherry-pick conflict on <sha>
  
  Conflicted files:
  <git diff --name-only --diff-filter=U output>
  
  Options:
  1. Pause — I'll resolve the conflict manually, then you continue
  2. Abort — run `git cherry-pick --abort` and delete the backport branch
  3. Skip — run `git cherry-pick --skip` and move on (rebase mode only)
  
  Choose (1-3):

  • Option 1 (pause): wait for user to resolve, then run:

    git status

    Confirm no unmerged paths remain, then:

    git cherry-pick --continue

  • Option 2 (abort):

    git cherry-pick --abort
    # Switch to a safe branch before deleting the backport branch.
    # Use the local target branch if it exists; otherwise create it tracking origin.
    git show-ref --verify --quiet refs/heads/<TARGET_BRANCH> \
      && git checkout <TARGET_BRANCH> \
      || git checkout -b <TARGET_BRANCH> --track origin/<TARGET_BRANCH>
    git branch -D backport/<target-sanitized>/pr-<pr-number>

    Stop the skill and report failure.
  • Option 3 (skip): only valid in rebase mode with multiple commits:

    git cherry-pick --skip

After all commits are applied, verify:

git log --oneline origin/<TARGET_BRANCH>..HEAD

Show the list of new commits to the user for confirmation.