Help backport PRs to release branches using the backport CLI tool. Use when backporting changes that have merge conflicts requiring manual resolution.
npxskills add cockroachdb/cockroach--skill backport-pr-assistantLoading…
Help the user backport pull requests to older release branches, especially when conflicts need resolution.
Always pass --no-browser to prevent the backport tool from opening browser
windows. If --no-browser is not recognized, the user has an old version of the
tool — upgrade it by running go install github.com/cockroachdb/backport@latest
and retry.
Basic Usage:
backport --no-browser <pull-request>... # Backport entire PR(s)
backport --no-browser <pr> -r <release> # Target specific release (e.g., -r 23.2)
backport --no-browser <pr> -b <branch> # Target specific branch (e.g., -b release-23.1.10-rc)
backport --no-browser <pr> -j "justification" # Add release justification
backport --no-browser <pr> -c <commit> -c <commit> # Cherry-pick specific commits only
backport --no-browser <pr> -f # Force operation
Conflict Resolution:
backport --continue # Resume after resolving conflicts
backport --abort # Cancel in-progress backport
Common Examples:
backport --no-browser 23437 # Simple backport
backport --no-browser 23437 -r 23.2 # To release-23.2 branch
backport --no-browser 23437 -j "test-only changes" # With justification
backport --no-browser 23437 -b release-23.1.10-rc # To specific release candidate branch
When the user specifies exact release branches, use those directly. When the user says something like "backport to all branches" or "backport to all supported releases" without listing specific versions, determine which branches are still supported by fetching the CockroachDB release support policy page:
https://www.cockroachlabs.com/docs/releases/release-support-policy
The page contains two tables: Supported versions and Unsupported versions. Only backport to versions whose Maintenance Support end date has not yet passed — versions in the Assistance Support phase only receive critical security fixes, not general bug-fix backports. Skip any version that appears in the Unsupported versions table (it is EOL). Pay attention to Innovation releases — they have shorter support windows and no Assistance Support phase, so they may have recently gone EOL.
Before starting the first backport, prompt the user for a release justification
(e.g., "bug fix for potential data loss", "test-only changes", "security patch").
Use the same justification across all backport PRs. Pass it to every backport
invocation via -j.
backport --no-browser <pr> -r <release> -j "<justification>" for the target branchgit add the resolved filesbackport --continue to resumegh pr create (see "Creating Backport PRs" below)Only create PRs when the user explicitly requests it. Use gh pr create with the
following conventions:
PR Title Format:
release-XX.X: <original PR title>
The title is the release branch prefix, a colon, a space, and then the original PR title verbatim. For example, if the original PR title is "keys: handle case where keys targeted by GC request straddle header" and the target branch is release-24.3, the backport PR title should be:
release-24.3: keys: handle case where keys targeted by GC request straddle header
PR Body Format:
Match the standard body format used by the backport tool:
Backport N/N commits from #<original-pr> on behalf of @<user>.
----
<original PR commit messages or body>
----
Release justification: <justification>
Example gh pr create invocation:
gh pr create \
--repo cockroachdb/cockroach \
--base release-24.3 \
--head <user>:backport24.3-<pr-number> \
--title "release-24.3: <original title>" \
--body "<body following the format above>"
Simple conflicts you can resolve directly:
Complex conflicts - ask the user for guidance:
git add <files> then backport --continue
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).