- 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.
Your environment — either parsed from config files (--config-path) or built from intake questions. Determines which plugins, auth providers, and features you use.
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.
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.
--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 |
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. |
|
|
| 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 |
|
|
|
- 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
1---2name: rhdh-upgrade-helper3description: 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.4---56<objective>7Help 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.8</objective>910<quick_start>11Invoke with:1213- Config file: `/rhdh-upgrade-helper` (reads `.rhdh-upgrade-helper.yaml` from cwd)14- Individual files: `/rhdh-upgrade-helper --to 1.10 --config ./values.yaml --config ./app-config.yaml`15- Directory: `/rhdh-upgrade-helper --to 1.10 --config-path ./my-configs/`16- Interactive: `/rhdh-upgrade-helper --to 1.10`17- Skip-release: `/rhdh-upgrade-helper --from 1.8 --to 1.10 --config ./values.yaml`1819Arguments: `[--to X.Y] [--from X.Y] [--config /path/to/file] [--config-path /dir]`2021- **--to X.Y** (required): Target RHDH release version to upgrade TO.22- **--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`).23- **--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.24- **--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.25- 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`.26</quick_start>2728<context>29This skill uses two data sources:30311. **Your environment** — either parsed from config files (`--config-path`) or built from intake questions. Determines which plugins, auth providers, and features you use.32332. **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.34353. **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.3637The skill correlates these to answer: "Of all the changes in the target release, which ones actually affect MY setup?"3839### Config file4041When 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`.4243### Config analysis4445When 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.4647### Security4849All 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.50</context>5152<routing>53| Condition | Workflow |54|-----------|----------|55| Config files resolved (via `.rhdh-upgrade-helper.yaml`, `--config`, or `--config-path`) | `workflows/full-report.md` (config-driven assessment) |56| No config files resolved | `workflows/interactive.md` (ask intake questions, then assess) |57| "help", "explain", "how" | `workflows/help.md` |5859**`--to` is always required.** If omitted, prompt for it before routing. `.rhdh-upgrade-helper.yaml` may provide it.60**When no config files are resolved, always route to `workflows/interactive.md` — never produce a generic report without gathering environment context first.**61</routing>6263<reference_index>6465| Reference | Purpose |66|-----------|---------|67| `references/config-scoring.md` | Readiness scoring model — base score from config findings, amplifiers, mitigators. Positive framing (90 = ready). |68| `references/output-format.md` | Customer-facing report template — migration steps first, "Does NOT Affect You" section, upgrade checklist. |69| `references/intake-questions.md` | Interactive environment questionnaire — 7 questions that build an `$ENVIRONMENT_PROFILE`. |70| `references/secrets-detection.md` | Secret patterns to scan for before processing config files. Template refs are safe; literal secrets are flagged. |71| `references/rhdh-local.md` | RHDH Local detection and recommendation for safe pre-upgrade testing. |72| `references/env-vars.md` | Known RHDH environment variables that affect upgrade behavior. |73| `references/rhdh-upgrade-helper-config.md` | `.rhdh-upgrade-helper.yaml` format, resolution order, file type auto-detection, Helm and Operator examples. |74| `references/config-analysis.md` | How to parse customer config files — content-based auto-detection for Helm values, app-config, dynamic-plugins, and Backstage CR. |75| `references/rhdh-architecture.md` | RHDH architecture context — what actually breaks on upgrade vs. common false positives. |76| `references/release-notes/{X.Y}.md` | Per-release notes (new features, breaking changes, deprecated/removed features, known issues). One file per release. |77</reference_index>7879<workflows_index>8081| Workflow | Purpose | Data Sources Used |82|----------|---------|-------------------|83| `workflows/full-report.md` | Config-driven upgrade assessment with line-level migration steps | Config analysis + product context |84| `workflows/interactive.md` | Guided Q&A to build environment profile, then runs full assessment | Intake questions + product context |85| `workflows/help.md` | Explain the skill and its capabilities | None |86</workflows_index>8788<anti_patterns>89<pitfall name="generic-advice-without-context">90Never 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.91</pitfall>9293<pitfall name="workspace-rename-false-positive">94**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`.95</pitfall>9697<pitfall name="showing-all-breaking-changes-equally">98Not 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.99</pitfall>100101<pitfall name="negative-framing">102Frame 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.103</pitfall>104105<pitfall name="internal-jargon">106This skill is customer-facing. Avoid: "Customer Focal," "RHDHSUPP," "ticket history," "correlation rules," "churn hotspots." Use: "your configuration," "your plugins," "your auth setup."107</pitfall>108109<pitfall name="downgrading-local-path-severity">110**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.111</pitfall>112113<pitfall name="processing-secrets">114Never 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.115</pitfall>116117<pitfall name="skipping-rhdh-local">118Always 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.119</pitfall>120121<pitfall name="findings-without-evidence">122**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.123</pitfall>124</anti_patterns>125126<success_criteria>127The report is complete when:128129- All config files scanned for secrets per `references/secrets-detection.md` before any analysis130- Target release resolved to Backstage version via overlay repo131- Customer's environment determined (from config or intake questions)132- Product context gathered for the release range133- Per-plugin bug search run against RHDHBUGS Jira (if accessible) and `redhat-developer/rhdh` GitHub Issues134- Every breaking change classified as "affects you" or "does NOT affect you" based on environment overlap135- Readiness score computed with transparent breakdown per `references/config-scoring.md`136- Migration actions are specific: file path, line number (when from config), current value, replacement, reason137- "Does NOT Affect You" section included to reduce upgrade anxiety138- RHDH Local recommended for pre-upgrade testing per `references/rhdh-local.md`139- Upgrade checklist provided at end of report140</success_criteria>
redhat-developer