| name | backport |
| description | Fetch a merged upstream Gerrit change, cherry-pick it to an internal GitLab stable branch, and prepare a merge request summary. Use when backporting upstream OpenStack patches, cherry-picking Gerrit changes, or preparing stable branch merge requests. |
Backport
You are backporting a merged upstream OpenStack Gerrit change to an internal GitLab repository stable branch. Your goal is to fetch the change, validate it, apply it via cherry-pick, augment the commit message with traceability metadata, and prepare a merge request for the user to review.
Agent Collaboration: Invoke the shared backport specialist persona for analysis:
- @backport-specialist.md — Invoke for dependency analysis (step 4) and conflict resolution guidance (step 8) to leverage stable branch knowledge, release mapping, and conflict explanation expertise
This skill supports multi-commit backports: you can run /backport multiple times to accumulate cherry-picks on the same branch, then create a single MR containing all commits via /create-mr.
Detailed process reference: See references/REFERENCE.md for the full step-by-step process with all sub-steps, MCP fallback paths, and error handling details.
Input
The user will provide one of:
- A Gerrit change URL (e.g.,
https://review.opendev.org/c/openstack/nova/+/912345)
- A Gerrit change numeric ID (e.g.,
912345)
Process Overview
1. Parse Input
Extract the change ID from the provided URL or use the numeric ID directly. URL format: https://review.opendev.org/c/{project}/+/{change_id}.
2. Fetch Change Metadata
Check Gerrit MCP availability via workflows/shared/scripts/detect-mcp.sh gerrit. Use MCP if available, otherwise fall back to REST API (gerrit-fetch-metadata.sh), then manual entry. Present the change summary (subject, author, project, branch, status) to the user for confirmation.
3. Validate Status
Verify the change status is MERGED. Do not proceed with non-merged changes.
4. Analyze Dependencies and Check for Reverts
- Revert check (MCP only): Query for merged reverts of the target change
- Dependency chain (MCP only): Check parent commits and topic-related changes
- Deferred verification: After cloning (step 7), verify dependencies exist on the target stable branch. Write
deps-{change_id}.md artifact if missing dependencies found
5. Prompt for Target
Check for existing backport branches (backport/*). If found, offer to add commits to an existing branch or create a new one. For new branches, ask for GitLab project path and stable branch name. Validate branch exists via git ls-remote or glab CLI if available.
6. Prompt for Metadata
Ask for upstream release name (e.g., Wallaby, Zed, 2024.2) and optional Jira issue key. Skipped for existing backport sessions (metadata inherited).
7. Clone and Cherry-Pick
- Clone/fetch the internal GitLab repository (MCP, HTTPS, or SSH failover)
- Checkout the target stable branch and pull latest
- Create backport branch:
backport/<change_id>-to-<stable_branch> (new sessions only)
- Fetch upstream commit via MCP or
gerrit-git-fetch.sh refspec
- Cherry-pick:
git cherry-pick -x <commit_hash>
8. Handle Conflicts
If cherry-pick conflicts occur:
- Identify conflicting files with
git diff --name-only --diff-filter=U
- Present each conflict with context and upstream intent explanation
- Write conflict artifact to
artifacts/gerrit-to-gitlab/conflict-{change_id}.md
- Wait for user to resolve, then collect resolution notes for commit message
- Stage resolved files and
git cherry-pick --continue
- Offer abort option:
git cherry-pick --abort
9. Augment Commit Message
Amend the commit message (git commit --amend) to append after the cherry-pick line:
Upstream-<Release>: <gerrit-change-url>
Resolves: <Jira-issue-key> # only if applicable
Conflicts: # only if conflicts occurred
* <file_path>
<resolution description>
10. Present MR Summary
Show the merge request summary (title, branches, commit message, changed files). For multi-commit sessions, include a table of all commits on the branch.
11. Write Artifact
Save to artifacts/gerrit-to-gitlab/backport-{change_id}.md with change metadata, target info, cherry-pick result, session state, and MR draft.
12. Offer MR Creation
Offer to create the MR via /create-mr or add more commits via another /backport run.
Error Conditions
| Condition | Behavior |
|---|
| Change not found | Report: "Could not find Gerrit change {id}. Please verify the URL or ID." |
| Change not MERGED | Report: "This change has status '{status}'. Only merged changes can be backported." |
| Gerrit MCP unavailable | Fall back to REST API metadata fetch, then git refspec fetch |
glab CLI unavailable | Fall back to HTTPS/SSH git operations |
| REST API metadata fetch fails | Fall back to manual metadata entry |
| Git fetch fails (both methods) | Report error with remediation steps |
| SSH key invalid | Report error, allow retry or cancellation |
| Stable branch not found | List available branches via git ls-remote or skip validation |
| Cherry-pick fails (not conflict) | Report the git error and suggest manual intervention |
Output
Artifact: artifacts/gerrit-to-gitlab/backport-{change_id}.md
Writing Style
Follow the rules in rules.md. In particular:
- Be specific — cite change IDs, file paths, and commit hashes
- Explain what the upstream change does before showing the MR summary
- Each error message should be self-contained and actionable
- Distinguish between MCP unavailable (using fallback), network errors, authentication errors, and operation failures
