/scan

Name

acm-fix-search:scan - Scan ACM operator bundles to check if bundled images include configured Git fixes

Synopsis

/acm-fix-search:scan [--debug] [--catalog-source-version VERSION] [--acm-bug-number BUG_ID ...]

Description

The scan command runs map_acm_fix_bundles.py against the configured operator index to determine which ACM bundle versions include specific Git fixes. It renders all ACM (and auxiliary) bundles from the OLM catalog, extracts container images from each bundle's ClusterServiceVersion, inspects vcs-ref labels, and uses the GitHub compare API to verify fix ancestry.

This command:

• Runs dependency preflight checks (podman, registry auth, Python 3, opm) and stops with explicit remediation instructions if anything is missing
• Accepts --catalog-source-version to dynamically select the OCP catalog version (e.g. v4.17, v4.20, v4.22) instead of relying on a hardcoded default
• Accepts --acm-bug-number to dynamically search GitHub for merged PRs matching a bug ID (e.g. ACM-35768) and create FixChecks on the fly — replacing hardcoded checks with real-time discovery
• Streams olm.bundle objects from the operator index via opm render
• For each ACM bundle version, checks every configured FixCheck against the corresponding image's vcs-ref
• Outputs a formatted table showing bundle version, fix status, and details

Prerequisites

1. podman: Must be installed and able to pull from registry.redhat.io
2. Registry auth: podman login registry.redhat.io must have been run
3. Python 3: Required to execute the script
4. GITHUB_TOKEN or GH_TOKEN (optional but recommended): Avoids GitHub API rate limits

Implementation

1. Check prerequisites:

   command -v podman && command -v python3
   

   If missing, inform the user and stop.

2. Determine the script path:

   • Look for map_acm_fix_bundles.py in the current directory or the plugin's root directory.

3. Run the scan:

   python3 map_acm_fix_bundles.py [-d] [--catalog-source-version VERSION] [--acm-bug-number BUG_ID ...]
   

   Pass -d if the user requested --debug. Pass --catalog-source-version if the user specified a version. Pass --acm-bug-number for each bug ID the user wants to check (can be repeated).

4. Parse the TSV output (tab-separated):

   • Header: bundle_version, bundle_name, all_fixes_ok, acm_siteconfig_image, acm_siteconfig_vcs, fix_results
   • all_fixes_ok: True only if every FixCheck passed for that bundle
   • fix_results: pipe-separated label: detail entries per check

5. Present results in a formatted table:

   • Sort by bundle version
   • Highlight rows where all_fixes_ok is True
   • Show per-fix details in an expandable section if many fixes are configured

6. Summarize:

   • Count of bundles scanned
   • Count of bundles where all fixes are present
   • List the earliest bundle version that includes all fixes (if any)

Environment Variables

Variable	Description
MAP_ACM_OPERATOR_INDEX	Operator index image (overrides --catalog-source-version; default version: v4.20)
GITHUB_TOKEN / GH_TOKEN	GitHub personal access token for API calls
MAP_ACM_OPM_HOST	Set to 1 to force host opm binary instead of containerized
MAP_ACM_OPM_CONTAINER_IMAGE	Override the opm container image
MAP_ACM_OPM_SKIP_TLS	Set to 1 to pass --skip-tls to opm
MAP_ACM_ASSISTED_CSV_BUNDLE_VERSION	Override MCE bundle version for assisted FixChecks

Examples

1. Basic scan (uses default catalog version v4.20):

   /acm-fix-search:scan
   

2. Scan with debug output:

   /acm-fix-search:scan --debug
   

3. Scan a specific OCP catalog version:

   /acm-fix-search:scan --catalog-source-version v4.22
   

4. Scan an older sqlite-based index:

   /acm-fix-search:scan --catalog-source-version v4.17
   

5. Search for a specific bug across the v4.22 catalog:

   /acm-fix-search:scan --catalog-source-version v4.22 --acm-bug-number ACM-35768 --debug
   

6. Search for multiple bugs at once:

   /acm-fix-search:scan --acm-bug-number ACM-35768 --acm-bug-number ACM-23882
   

Return Value

• Success: Formatted table of bundle versions and fix status
• Failure: Error message with diagnostics (auth issues, missing tools, network errors)

Arguments

• --debug / -d: Optional flag to enable verbose debug output to stderr
• --catalog-source-version VERSION: OCP catalog index version tag (e.g. v4.17, v4.20, v4.22). Overridden by MAP_ACM_OPERATOR_INDEX env var if set
• --acm-bug-number BUG_ID: Dynamically search GitHub for merged PRs matching this bug ID (e.g. ACM-35768). Discovers anchor SHAs and repos automatically. Replaces hardcoded FIX_CHECKS when specified. Can be repeated for multiple bugs
• --skip-dep-check: Skip dependency preflight checks (not recommended)