acm-fix-search

ACM Fix Search

Verify whether specific Git fixes are shipped in Red Hat Advanced Cluster Management (ACM) operator bundles. The tool scans an OLM operator index, extracts container images from each ACM bundle's ClusterServiceVersion, reads the Git commit each image was built from, and uses the GitHub compare API to determine fix ancestry.

This project ships as an AI-agent plugin for Claude Code, Cursor, and OpenCode so that every command is available as a natural-language action inside your editor or terminal.

---

Table of Contents

• How It Works
• Prerequisites
• Installation
  • Claude Code
  • Cursor
  • OpenCode
• Plugin Commands
  • acm-fix-search:scan
  • acm-fix-search:add-fix
  • acm-fix-search:list-fixes
  • acm-fix-search:check-prereqs
  • acm-fix-search:set-index
• Subagent: acm-fix-analyzer
• Environment Variables
• Configuring Fix Checks
• Output Format
• Contributing
• License

---

How It Works

Operator Index (OLM catalog, selected via --catalog-source-version)
        |
        v
    opm render  ──>  stream olm.bundle objects (ACM + MCE packages)
        |
        v
    For each bundle version, extract image refs from the
    ClusterServiceVersion YAML using a regex pattern
        |
        v
    podman inspect  ──>  read the vcs-ref label (Git commit the image was built from)
        |
        v
    GitHub compare API:  GET /repos/{owner}/{repo}/compare/{anchor}...{vcs}
        |
        v
    If merge-base == anchor  AND  status in (ahead, identical)
        => fix IS present in this bundle version
    Otherwise
        => fix is NOT present (with a detailed reason)
        |
        v
    TSV output: bundle_version | all_fixes_ok | fix_results

The tool supports two image types out of the box:

Fix target	Image regex variable	CSV source
stolostron/siteconfig	SITEIMAGE_SITECONFIG	ACM bundle CSV
openshift/assisted-service	SITEIMAGE_ASSISTED	MCE (multicluster-engine) bundle CSV

For assisted-service fixes the tool automatically maps ACM 2.y.z to MCE 2.(y-5).z (same patch level):

ACM version	Paired MCE version
2.13.x	2.8.x
2.14.x	2.9.x
2.15.x	2.10.x
2.16.x	2.11.x

---

Prerequisites

Tool	Required	Purpose
Python 3	Yes	Runs map_acm_fix_bundles.py
podman	Yes	Pulls operator index and bundle images, inspects vcs-ref labels
Registry credentials	Yes	podman login registry.redhat.io must succeed before scanning
GITHUB_TOKEN or GH_TOKEN	Recommended	Avoids GitHub API rate limits (60 req/hr unauthenticated vs 5 000 authenticated)
opm	Optional	Host binary used for opm render; if absent the script runs opm inside a container via podman automatically

# One-time setup
podman login registry.redhat.io
export GITHUB_TOKEN=ghp_your_token_here

You can verify everything is in place at any time with the check-prereqs command (see below). The script also runs these checks automatically at startup and exits with explicit remediation messages if anything is missing:

╔══════════════════════════════════════════════════════════╗
║            MISSING DEPENDENCIES                        ║
╚══════════════════════════════════════════════════════════╝

  [1] podman is not installed or not on PATH. ...
      Install: dnf install podman  (Fedora/RHEL)

  [2] No registry credentials found for registry.redhat.io. ...
      Fix: podman login registry.redhat.io

---

Installation

Claude Code

The plugin is defined in .claude-plugin/plugin.json with commands in commands/ and a subagent in agents/.

Install from the acm-fix-search registry:

/plugin install midu16/acm-fix-search

Or install from a local clone:

git clone https://github.com/midu16/acm-fix-search.git
cd acm-fix-search

Once the plugin is installed, all five commands are available as /acm-fix-search:<command> slash commands inside any Claude Code session (CLI, desktop app, web app, or IDE extension) that has the plugin enabled.

Plugin structure:

.claude-plugin/
  plugin.json             # manifest (name, version, author, keywords)
commands/
  scan.md                 # /acm-fix-search:scan
  add-fix.md              # /acm-fix-search:add-fix
  list-fixes.md           # /acm-fix-search:list-fixes
  check-prereqs.md        # /acm-fix-search:check-prereqs
  set-index.md            # /acm-fix-search:set-index
agents/
  acm-fix-analyzer.md     # read-only subagent for result analysis