rhdh-upgrade-helper

name

rhdh-upgrade-helper

description

Customer-facing upgrade assessment for RHDH. Analyzes your configuration files (or asks about your environment) against a target RHDH release to produce a concrete migration plan with readiness scoring. Use when upgrading RHDH, planning a migration, checking what breaks in a new version, assessing upgrade impact, or asking "can I upgrade to X.Y", "what changed between versions", "migration guide", "upgrade checklist", "is my config compatible". No Jira access or Red Hat subscription required.

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.

<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>

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.

2. 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.

3. 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.

| Condition | Workflow | |-----------|----------| | Config files resolved (via `.rhdh-upgrade-helper.yaml`, `--config`, or `--config-path`) | `workflows/full-report.md` (config-driven assessment) | | No config files resolved | `workflows/interactive.md` (ask intake questions, then assess) | | "help", "explain", "how" | `workflows/help.md` |

--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.

<reference_index>

Reference	Purpose
references/config-scoring.md	Readiness scoring model — base score from config findings, amplifiers, mitigators. Positive framing (90 = ready).
references/output-format.md	Customer-facing report template — migration steps first, "Does NOT Affect You" section, upgrade checklist.
references/intake-questions.md	Interactive environment questionnaire — 7 questions that build an $ENVIRONMENT_PROFILE.
references/secrets-detection.md	Secret patterns to scan for before processing config files. Template refs are safe; literal secrets are flagged.
references/rhdh-local.md	RHDH Local detection and recommendation for safe pre-upgrade testing.
references/env-vars.md	Known RHDH environment variables that affect upgrade behavior.
references/rhdh-upgrade-helper-config.md	.rhdh-upgrade-helper.yaml format, resolution order, file type auto-detection, Helm and Operator examples.
references/config-analysis.md	How to parse customer config files — content-based auto-detection for Helm values, app-config, dynamic-plugins, and Backstage CR.
references/rhdh-architecture.md	RHDH architecture context — what actually breaks on upgrade vs. common false positives.
references/release-notes/{X.Y}.md	Per-release notes (new features, breaking changes, deprecated/removed features, known issues). One file per release.
</reference_index>

<workflows_index>

Workflow	Purpose	Data Sources Used
workflows/full-report.md	Config-driven upgrade assessment with line-level migration steps	Config analysis + product context
workflows/interactive.md	Guided Q&A to build environment profile, then runs full assessment	Intake questions + product context
workflows/help.md	Explain the skill and its capabilities	None
</workflows_index>

<anti_patterns> 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.

**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`. 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. 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. This skill is customer-facing. Avoid: "Customer Focal," "RHDHSUPP," "ticket history," "correlation rules," "churn hotspots." Use: "your configuration," "your plugins," "your auth setup." **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. 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. 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. **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.

<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>