rhdh-backstage-upgrade
Moves the @backstage/* dependency versions of a Backstage plugin, workspace, app, or the redhat-developer/rhdh monorepo forward to a chosen release, staying within what a Red Hat Developer Hub version ships: read backstage.json and package.json, pick the target from the RHDH compatibility matrix or an explicit version, run versions:bump and versions:migrate, preserve the repository's dependency range style, audit stale resolutions, work through release changelogs, and re-verify the repository. Use for "upgrade @backstage dependencies", "bump Backstage in rhdh", "versions:bump", "which Backstage version does RHDH 1.8 ship", moved package namespaces, or dependencies that are too old for the API they need.
How do I install this agent skill?
npx skills add https://github.com/redhat-developer/rhdh-skills --skill rhdh-backstage-upgradeIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill facilitates Backstage dependency upgrades for Red Hat Developer Hub projects using standard tools like yarn and backstage-cli. It interacts with official Backstage manifest servers and GitHub repositories. A minor security surface exists for indirect prompt injection from external changelogs or manifests, which is a common risk for developer tools that ingest remote documentation or metadata.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
RHDH Backstage Upgrade
Own version numbers. Which @backstage/* release a checkout sits on, which
release it should move to, and everything that breaks in between.
Start here
- Read
package.jsonandbackstage.jsonbefore changing any dependency. - Establish the target RHDH version. Prefer an explicit user or repository
value; otherwise invoke
/rhdh-contextfor the checked-in compatibility matrix. If it is unavailable, ask the user for the target RHDH and Backstage versions rather than guessing. - Report current versions and the proposed target before running a bump.
Route by outcome
| Outcome | Load and follow |
|---|---|
| Run the whole upgrade | workflows/upgrade-backstage.md |
| Find the current versions and any misalignment | references/discover-versions.md |
| Choose the target release | references/determine-target.md |
| Bump the dependency set | references/bump-deps.md |
| Move imports off renamed or relocated packages | references/migrate-packages.md |
| Work through the breaking changes between releases | references/fix-breaking-changes.md |
| Verify the upgrade | references/verify-upgrade.md |
Boundaries
- This skill owns version numbers. It does not change what a plugin's extensions are or how they attach.
/rhdh-plugin-nfs-migrationowns extension shape: converting a legacy frontend plugin's extensions into New Frontend System Blueprints. The two skills meet whenever an upgrade is a prerequisite for a migration, or a migration surfaces an outdated dependency set. Bump the versions here; change the extensions there./backstage-api-changesowns the NFS API deltas between the early alpha and the current GA surface. Invoke it by name when an upgrade breaks NFS code — a removedNavItemBlueprint, aconfig.schemablock that must becomeconfigSchema, or a renamed blueprint param./rhdh-contextowns the RHDH-to-Backstage compatibility matrix./rhdh-plugin-authoringowns non-mechanical source changes the upgrade exposes./rhdh-pr-createowns staging, commits, and pull requests.
Invoke a named skill and describe the handoff in the conversation. Never open another skill's files.
Invariants
- Never upgrade past the Backstage version the target RHDH release ships. The resolved compatibility answer wins over the newest available release.
- Use the checkout's
versions:bumpscript when it wrapsbackstage-cli versions:bump; otherwise use the CLI directly. Review the resultingpackage.jsonand lockfile diff before continuing. - Inventory every resolution and override before the bump. Compare its package manager dependency paths before and after, then record the provenance and evidence for keeping, updating, or removing it.
- Read the changelog for every release between the old and new version, then search the source for each affected API. Do not assume a range is breaking-change free.
- If current and target match, say "already on target" and stop.
- Run every validation command the checkout defines for build, test, lint, formatting, and monorepo consistency before reporting the upgrade complete.
- Do not stage, commit, push, or open a pull request here.
Completion
Report the versions found, the target chosen and where the answer came from, the commands run, the breaking changes fixed and the files they touched, every resolution and override with its provenance, before/after graph evidence and keep/update/remove reason, any range-style change, generated files, the verification results, and any dependency left misaligned with a reason.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/redhat-developer/rhdh-skills/rhdh-backstage-upgrade">View rhdh-backstage-upgrade on skillZs</a>