Ironic Backport Agent

AI-assisted automation for backporting upstream Ironic changes across OpenShift release branches.

Works with Claude Code - No separate API keys needed!

Project Goal

Automate the repetitive backport workflow for OpenShift BareMetal/Ironic releases using Claude AI for intelligent decision-making. Runs as an MCP server that integrates seamlessly with Claude Code.

JIRA Epic: METAL-1814
Research Spike: METAL-1817

How It Works

Instead of using CLI commands, you talk to Claude naturally:

You: "Backport PR #370 to release-4.20"

Claude: [analyzes PR] "I found 3 commits. Based on the changes,
        only commit 42ac11d31 should be backported. Proceed?"

You: "Yes"

Claude: [executes backport, creates PR] "✅ Done! PR #456 created"

Features

🤖 AI-Powered (via Claude Code)

• Analyzes PRs to recommend which commits to backport
• Determines which release branches need the fix
• Suggests merge conflict resolutions
• Generates PR titles and descriptions following OpenShift conventions
• Adapts to errors and retries intelligently

⚙️ Automated Operations

• Git cherry-pick with conflict detection
• Branch management and analysis
• GitHub PR creation with proper formatting
• Dependency file updates (requirements.cachito, main-package-list.ocp)

💬 Natural Conversation

• No commands to memorize - just describe what you want
• Context-aware - Claude remembers the conversation
• Human oversight - You approve critical steps naturally
• Audit trail built into Claude conversation history

Quick Start

1. Install

cd /Users/jhajyahy/ironic-backport-agent
./install.sh

2. Configure

# Only need GitHub token - no Claude API key!
export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"

Get token from: https://github.com/settings/tokens (scopes: repo + workflow)

3. Set Up MCP

Add to ~/.claude/config.json:

{
  "mcpServers": {
    "ironic-backport": {
      "command": "python",
      "args": ["/Users/jhajyahy/ironic-backport-agent/src/backport_agent/mcp_server.py"],
      "env": {"GITHUB_TOKEN": "${GITHUB_TOKEN}"}
    }
  }
}

4. Restart Claude Code

The backport tools will now be available in your Claude Code session!

📖 See SETUP-MCP.md for detailed setup guide.

Config File

Create config.yaml:

github:
  base_org: openshift
  repos:
    - openstack-ironic
    - ironic-image
    - ironic-python-agent-image

claude:
  model: claude-sonnet-4-5
  max_tokens: 4096

release_branches:
  - release-4.17
  - release-4.18
  - release-4.19
  - release-4.20
  - release-4.21
  - release-4.22

workflow:
  auto_approve: false
  conflict_strategy: ai_suggest

Usage Examples

Simple Backport

You: "Backport PR #370 from openstack-ironic to release-4.20"

Claude: "I found PR #370 with 3 commits. Analyzing..."
        [uses analyze_pr tool]
        
        "Based on the changes:
        - 42ac11d31: Update heartbeat ✓ BACKPORT
        - abc123de4: Update dev deps ✗ SKIP
        - def456g78: Fix pep8 ✗ SKIP
        
        Proceed with backporting commit 42ac11d31?"

You: "Yes"

Claude: [creates branch, cherry-picks, creates PR]
        "✅ PR created: https://github.com/.../pull/456"

Check Branch Coverage

You: "Does release-4.20 already have commit 42ac11d31?"

Claude: [uses analyze_branch_coverage tool]
        "No, it's not in release-4.20.
        Present in: release-4.21, release-4.22
        Would you like to backport it?"

Batch Backport

You: "Backport PR #370 to all active releases"

Claude: "Analyzing which branches need this fix..."
        [checks each branch]
        
        "Results:
        - release-4.18: Needs it ✓
        - release-4.19: Needs it ✓
        - release-4.20: Needs it ✓
        - release-4.21: Already has it ✗
        - release-4.22: Already has it ✗
        
        Create 3 backport PRs?"

You: "Yes"

Claude: [creates PRs for 4.18, 4.19, 4.20]
        "✅ All done!
        - 4.18: PR #457
        - 4.19: PR #458
        - 4.20: PR #459"

Conflict Handling

You: "Backport commit 42ac11d31 to release-4.20"

Claude: [attempts cherry-pick]
        "⚠️ Conflict in ironic/conductor/manager.py
        
        Analyzing..."
        [reads conflict content]
        
        "The conflict is in import order. Suggested resolution:
        - Use THEIR version for update_heartbeat function
        - Keep OURS version for imports
        
        Apply this?"

You: "Yes"

Claude: [resolves conflict, completes cherry-pick]
        "✅ Resolved and cherry-picked!"

Architecture

See ARCHITECTURE.md for detailed design documentation.

Development

Run Tests

pytest tests/ -v --cov=backport_agent

Code Quality

# Format
black src/

# Lint
ruff check src/

# Type check
mypy src/

METAL-1817 Research Findings

This prototype addresses all research questions from the spike:

✅ Branch Analysis

• Implemented via git branch --contains and AI-assisted applicability detection
• See: src/backport_agent/git_ops.py:analyze_branch_coverage()

✅ Cherry-Pick Automation

• Conflict detection with AI-suggested resolutions
• See: src/backport_agent/git_ops.py:cherry_pick_with_ai()

✅ GitHub Integration

• PAT scope requirements documented above
• PR creation via PyGithub with proper title format
• See: src/backport_agent/github_client.py

✅ Dependency File Updates

• AI determines which file to update (requirements.cachito vs main-package-list.ocp)
• Automated hash updates
• See: src/backport_agent/dependency_updater.py

✅ GitLab Integration

• Python-gitlab for ospinfo repos
• See: src/backport_agent/gitlab_client.py

Roadmap

• METAL-1817: Git/GitHub/GitLab integration research
• METAL-1820: Phase 1 prototype (Scenario A)
• METAL-1821: JIRA API integration
• METAL-1819: CI monitoring
• METAL-1822: Brew/Koji support (Scenario B)
• METAL-1823: Optimized semi-autonomous mode
• METAL-1824: Production deployment

Contributing

This is a team effort! See the Slack channel for coordination.

License

Internal Red Hat tooling - not for public distribution.