Revert PR

Revert PR

This skill provides the detailed git revert workflow and the exact PR body template used by Revertomatic for reverting merged pull requests that break CI or nightly payloads.

When to Use This Skill

Use this skill when:

• A merged PR needs to be reverted to restore CI signal
• Following the OpenShift quick-revert policy
• You need the exact Revertomatic template format for the revert PR body
• You need to generate CI override commands for a revert PR

Optional Parameters

• --draft: When set, create the revert PR as a draft (gh pr create --draft). Used by the experimental revert workflow to open experimental revert PRs that may be closed if the suspect is cleared.
• --context: When the caller passes context directly (e.g., from an autonomous pipeline that already has all context in memory), skip the JIRA lookup in Step 5. The provided context string is used as-is for the {CONTEXT} template variable.

Prerequisites

1. GitHub CLI (gh): Installed and authenticated

   • Check: gh auth status

2. Git: Installed and configured

   • Check: which git

3. Repository Access: User must have push access to their fork of the target repository

Implementation Steps

Step 1: Extract PR Information

Use the gh CLI to fetch all necessary details about the PR being reverted:

# Fetch PR details as JSON
pr_data=$(gh pr view "$PR_URL" --json number,title,author,mergeCommit,baseRefName,state)

# Extract fields
pr_number=$(echo "$pr_data" | jq -r '.number')
pr_title=$(echo "$pr_data" | jq -r '.title')
pr_author=$(echo "$pr_data" | jq -r '.author.login')
merge_sha=$(echo "$pr_data" | jq -r '.mergeCommit.oid')
base_branch=$(echo "$pr_data" | jq -r '.baseRefName')
pr_state=$(echo "$pr_data" | jq -r '.state')

Validation:

• pr_state must be MERGED. If the PR is not merged, abort with an error.
• merge_sha must not be empty or null.

Step 2: Identify the Upstream Repository

Parse the PR URL to determine owner and repository:

# From URL like https://github.com/openshift/kubernetes/pull/1703
# Extract: owner=openshift, repo=kubernetes

Step 3: Ensure User Has a Fork

# Get authenticated user
gh_user=$(gh api user --jq '.login')

# Check if fork exists; create one if not
if ! gh api "repos/$gh_user/$repo" &>/dev/null; then
    echo "Creating fork of $owner/$repo..."
    gh repo fork "$owner/$repo" --clone=false
    # Wait for fork to become available
    sleep 5
fi

Step 4: Clone and Set Up Repository

If no local repository is available:

# Clone upstream repo
git clone -b "$base_branch" "https://github.com/$owner/$repo.git" /tmp/revert-workdir
cd /tmp/revert-workdir

# Rename the default remote to 'upstream' so later steps can reference it consistently
git remote rename origin upstream

# Add the user's fork as the 'fork' remote (used for pushing the revert branch)
git remote add fork "git@github.com:$gh_user/$repo.git"

If using an existing local clone, ensure upstream points to the canonical repo and fork points to the user's fork:

# Verify remotes: 'upstream' must point to the canonical repo, 'fork' to the user's fork
git remote -v

# If 'upstream' is missing but 'origin' points to the canonical repo, rename it:
# git remote rename origin upstream

# If 'fork' is missing, add it:
# git remote add fork "git@github.com:$gh_user/$repo.git"

Step 5: Look Up JIRA Ticket for Context

If --context was provided: Skip the JIRA lookup entirely. Use the provided context string as-is for the {CONTEXT} template variable and proceed to Step 6. The caller has already gathered all necessary context.

Otherwise, when a JIRA ticket is provided, use the fetch-jira-issue skill to automatically gather context about what broke and which jobs need verification before unreverting.

# Path to the fetch-jira-issue script
jira_script="plugins/ci/skills/fetch-jira-issue/fetch_jira_issue.py"

# Fetch JIRA issue details
jira_data=$(python3 "$jira_script" "$JIRA" --format json 2>/dev/null)

Extract context from the JIRA issue:

From the JSON output, examine the summary, comments, and linked_prs fields to determine:

1. What broke (for the {CONTEXT} template variable):

   • Look at the issue summary and description for mentions of failing jobs, payloads, or test names
   • Check comments for links to failing Prow jobs, payload pages, or Sippy reports
   • Look for patterns like e2e-aws, e2e-gcp, nightly, payload, or release stream URLs

2. Verification jobs (for the unrevert instructions):

   • Identify which specific CI jobs are mentioned as broken in the ticket
   • These are the jobs the original author should run before re-landing their change
   • Common patterns: e2e-aws, e2e-gcp, e2e-metal-ipi, e2e-ovn, etc.

# Example: Extract context from JIRA data
jira_summary=$(echo "$jira_data" | jq -r '.summary')
jira_comments=$(echo "$jira_data" | jq -r '.comments[].body')

# Look for job names and payload URLs in the summary and comments
# to build the CONTEXT and VERIFICATION variables

Fallback: If the JIRA lookup fails (no token, network error, or insufficient detail in the ticket), ask the user interactively:

• "Why is this PR being reverted?"
• "What jobs should be run to verify a fix before unreverting?"

If the user also provided inline context as arguments, combine it with the JIRA-derived context.

Step 6: Detect Commit Message Convention

YOU MUST ALWAYS DO THIS. Before creating the revert, check recent commits in the repository to determine if it uses a special commit/PR title prefix convention. Skipping this step will cause verify-commits CI jobs to fail.

# Check the last 20 commit subjects on the base branch
git log "upstream/$base_branch" --oneline -20

UPSTREAM carry convention: Some repositories (notably openshift/kubernetes and other repos carrying upstream patches) use the prefix format UPSTREAM: <tag>: in commit messages. Common tags include <carry>, <drop>, and upstream cherry-pick numbers like <12345>.

Detection logic:

• If a significant number of recent commits use the UPSTREAM: <tag>: format, the revert must follow the same convention.
• The revert commit message and PR title should use:

  UPSTREAM: <carry>: Revert "ORIGINAL_TITLE" because REASON

  For example:

  UPSTREAM: <carry>: Revert "UPSTREAM: 12345: Fix kubelet crash" because it broke e2e-aws jobs

• If the repo does NOT use this convention, use the standard format described in Step 9.

Store the detected convention for use in Steps 7 and 9.

Step 7: Create Revert Branch and Perform Revert

# Fetch latest from upstream
git fetch upstream

# Create revert branch from base branch
revert_branch="revert-${pr_number}-$(date +%s%3N)"
git checkout -b "$revert_branch" "upstream/$base_branch"

# Revert the merge commit (first parent = base branch)
git revert -m1 --no-edit "$merge_sha"

Important: The -m1 flag tells git to revert relative to the first parent of the merge commit, which is the base branch. This effectively undoes the changes introduced by the PR.

Amend Commit Message for UPSTREAM Convention

If the UPSTREAM convention was detected in Step 6, you MUST amend the revert commit message to include the appropriate UPSTREAM: <tag>: prefix. The default git revert message (Revert "...") will fail verify-commits CI checks.

Determine the appropriate tag by looking at the commit being reverted and the repo conventions (e.g., <carry>, <drop>).

# Set the tag based on the convention detected in Step 6
upstream_tag="carry"  # or "drop", or a cherry-pick number — based on context

# Get the current commit message
current_msg=$(git log -1 --format=%B)

# Prepend the UPSTREAM: <tag>: prefix to the first line
amended_msg=$(echo "$current_msg" | sed "1s/^/UPSTREAM: <$upstream_tag>: /")

# Amend the commit
git commit --amend -m "$amended_msg"

This transforms the commit message from:

Revert "Merge pull request #638 from author/branch"

to:

UPSTREAM: <carry>: Revert "Merge pull request #638 from author/branch"

Handling Merge Conflicts

If git revert fails with conflicts, determine the best strategy:

Strategy A: Resolve simple/obvious conflicts

Use this when conflicts are trivial and unambiguous:

• Generated files (go.sum, vendor directories, generated protobuf, etc.)
• One-line changes where the resolution is obvious
• Whitespace or formatting-only conflicts

To resolve:

1. Examine the conflicting files with git diff and git status
2. Resolve each conflict
3. Stage the resolved files with git add
4. Complete the revert with git revert --continue
5. IMPORTANT: Amend the revert commit message to note the conflict resolution:

   git commit --amend -m "$(git log -1 --format=%B)
   
   Note: Merge conflicts in {FILE_LIST} were resolved manually.
   Conflicts were trivial ({DESCRIPTION}, e.g. 'generated file regeneration', 'one-line context change')."

Strategy B: Revert dependent commits

Use this when conflicts are non-trivial, meaning later commits depend on the changes introduced by the PR being reverted:

1. Identify which subsequent commits conflict with the revert:

   # List commits after the merge commit on the base branch
   git log --oneline "$merge_sha"..upstream/"$base_branch"

2. Determine which of these commits touch the same files and depend on the reverted changes
3. Abort the current revert: git revert --abort
4. Revert in reverse chronological order — revert the dependent commits first, then the target commit:

   # Revert dependent commits first (newest to oldest)
   git revert --no-edit <dependent_sha_newest>
   git revert --no-edit <dependent_sha_next>
   # ... then revert the original target
   git revert -m1 --no-edit "$merge_sha"

5. IMPORTANT: Amend the final commit message (or use an interactive squash) to document what was reverted:

   Note: The following dependent commits were also reverted because
   they conflict with or depend on the original change:
   - <sha1> <title1>
   - <sha2> <title2>

6. Inform the user which additional commits were reverted and why, so the PR body can include this information

After conflict resolution (either strategy), push to the fork:

# Push to fork
git push fork "$revert_branch:$revert_branch"