rhdh-upgrade-helper

<objective> Help RHDH customers prepare for an upgrade by correlating their actual configuration (or described environment) with product changes between releases. Produces a prioritized migration checklist, readiness score, and a "Does NOT Affect You" section that shows which breaking changes are irrelevant to their setup. </objective>

<quick_start> Invoke with:

• Config file: /rhdh-upgrade-helper (reads .rhdh-upgrade-helper.yaml from cwd)
• Individual files: /rhdh-upgrade-helper --to 1.10 --config ./values.yaml --config ./app-config.yaml
• Directory: /rhdh-upgrade-helper --to 1.10 --config-path ./my-configs/
• Interactive: /rhdh-upgrade-helper --to 1.10
• Skip-release: /rhdh-upgrade-helper --from 1.8 --to 1.10 --config ./values.yaml

Arguments: [--to X.Y] [--from X.Y] [--config /path/to/file] [--config-path /dir]

• --to X.Y (required): Target RHDH release version to upgrade TO.
• --from X.Y (optional): Source RHDH release version upgrading FROM. Defaults to the release immediately before --to. Use when skipping releases (e.g., --from 1.8 --to 1.10).
• --config /path/to/file (optional, repeatable): Path to an individual config file. Can be specified multiple times. Accepts values.yaml, app-config.yaml, dynamic-plugins.yaml, Backstage CR, or any YAML with RHDH configuration. File type is auto-detected from content.
• --config-path /dir (optional): Path to a directory to scan for config files. When provided, scans for known file patterns. Can be combined with --config for additional files.
• When no config source is given, the skill checks for .rhdh-upgrade-helper.yaml in the current directory. If not found, it asks intake questions to build your environment profile. See references/rhdh-upgrade-helper-config.md.

</quick_start>

<context> This skill uses two data sources:

1. Your environment — either parsed from config files (--config-path) or built from intake questions. Determines which plugins, auth providers, and features you use.

1. Product context — release diffs, breaking changes, plugin version jumps, support level changes, bundle-to-OCI migrations. Gathered from the public rhdh-plugin-export-overlays overlay repo and RHDH release notes. Determines what changed between your current and target releases.

1. Known bug data — For each plugin in your config, the skill searches the RHDHBUGS Jira project for open bugs affecting that plugin in the target release. Also queries GitHub Issues on redhat-developer/rhdh for community-reported upgrade issues. If Jira is not accessible, falls back to GitHub Issues and release notes only.

The skill correlates these to answer: "Of all the changes in the target release, which ones actually affect MY setup?"

Config file

When a .rhdh-upgrade-helper.yaml file exists in the current directory (or in --config-path), the skill reads file paths and release versions from it. This avoids re-typing flags on repeat runs. See references/rhdh-upgrade-helper-config.md.

Config analysis

When config files are provided (via .rhdh-upgrade-helper.yaml, --config, or --config-path), parsing follows references/config-analysis.md. File type is auto-detected from content — supports Helm values, app-config, dynamic-plugins config, Backstage CR, and .env files.

Security

All config files are scanned for embedded secrets before processing. See references/secrets-detection.md. Template variable references (${VAR}) are safe — only literal secret values are flagged. </context>

<routing>

--to is always required. If omitted, prompt for it before routing. .rhdh-upgrade-helper.yaml may provide it. When no config files are resolved, always route to workflows/interactive.md — never produce a generic report without gathering environment context first. </routing>

<reference_index>

</reference_index>

<workflows_index>

</workflows_index>

<anti_patterns> <pitfall name="generic-advice-without-context"> Never produce migration advice without knowing the customer's environment. If no --config-path is given, ask intake questions first. "Update your auth config" is useless without knowing which auth provider they use. </pitfall>

<pitfall name="workspace-rename-false-positive"> Never predict breakage from upstream workspace renames. Customers configure plugins by OCI image and NPM package name, not workspace paths. A workspace rename does not change the plugin's package name, OCI image, or config keys. See references/rhdh-architecture.md. </pitfall>

<pitfall name="showing-all-breaking-changes-equally"> Not all breaking changes matter to every customer. The key value of this skill is FILTERING — showing which changes affect THIS customer's config and which do NOT. Always include both sections. </pitfall>

<pitfall name="negative-framing"> Frame the output positively. "Readiness Score: 85/100 — Ready with minor prep" not "Risk Score: 15 — Low Risk." The customer is preparing for an upgrade, not assessing danger. </pitfall>

<pitfall name="internal-jargon"> This skill is customer-facing. Avoid: "Customer Focal," "RHDHSUPP," "ticket history," "correlation rules," "churn hotspots." Use: "your configuration," "your plugins," "your auth setup." </pitfall>

<pitfall name="downgrading-local-path-severity"> Never downgrade local-path (./dynamic-plugins/dist/) findings from Critical. The default.packages.yaml lists NPM package names — it does NOT confirm that the local filesystem path ./dynamic-plugins/dist/plugin-name-dynamic still exists inside the target container image. These are different things. A plugin can exist in the default packages as an OCI reference while the local path was removed from the container image. The only safe path is to flag every ./dynamic-plugins/dist/ reference as Critical and recommend removal or OCI migration. See references/config-analysis.md Section 1. </pitfall>

<pitfall name="processing-secrets"> Never process literal secret values. Before analyzing any config file, scan for patterns defined in references/secrets-detection.md. If embedded secrets are detected, warn the user with file and line numbers and ask them to redact before continuing. Template variable references (${VAR_NAME}, {{ .Values.x }}) are NOT secrets — do not flag them. If the user chooses to continue despite warnings, replace detected secret values with [REDACTED] in all report output. </pitfall>

<pitfall name="skipping-rhdh-local"> Always recommend RHDH Local for safe pre-upgrade testing. If the customer's working directory does not contain an rhdh-local setup, include a recommendation in the report per references/rhdh-local.md. RHDH Local lets customers validate their updated configuration locally with podman compose before deploying to a cluster. </pitfall>

<pitfall name="findings-without-evidence"> **Never flag a finding as Critical or Important without concrete evidence from the RHDH release notes (references/release-notes/*.md), overlay repo workspace metadata, or Backstage changelogs.** Do not infer deprecation or breakage from naming conventions alone (e.g., "legacy" does not mean deprecated). Every Critical or Important finding must trace to a specific release notes entry or metadata change. If no evidence exists, either omit the finding or note it as Informational with an explicit caveat. </pitfall> </anti_patterns>

<success_criteria> The report is complete when:

• All config files scanned for secrets per references/secrets-detection.md before any analysis
• Target release resolved to Backstage version via overlay repo
• Customer's environment determined (from config or intake questions)
• Product context gathered for the release range
• Per-plugin bug search run against RHDHBUGS Jira (if accessible) and redhat-developer/rhdh GitHub Issues
• Every breaking change classified as "affects you" or "does NOT affect you" based on environment overlap
• Readiness score computed with transparent breakdown per references/config-scoring.md
• Migration actions are specific: file path, line number (when from config), current value, replacement, reason
• "Does NOT Affect You" section included to reduce upgrade anxiety
• RHDH Local recommended for pre-upgrade testing per references/rhdh-local.md
• Upgrade checklist provided at end of report

</success_criteria>