Backstage Upgrade

Always read the plugin's package.json (and backstage.json if present) before changing anything. Understand the current version baseline before upgrading.

RHDH pins specific Backstage versions per release. If the plugin targets RHDH, use the version matrix from ../rhdh/references/versions.md to determine the correct Backstage version. Don't blindly upgrade to the latest Backstage if it's ahead of what RHDH ships. Note: This path requires the rhdh core skill to be installed alongside. If the file is not found, ask the user for the target RHDH and Backstage versions directly.

Use backstage-cli versions:bump for dependency upgrades instead of manually editing package.json. The CLI resolves the correct version for every @backstage/* package from the release manifest.

This skill can be called standalone or chained from another skill (e.g., nfs-migration). When chained, the calling skill may pass additional breaking-change checklists. Apply those alongside the standard changelog review.

What would you like to do?

1. Upgrade to latest Backstage for my RHDH version — Align deps to the Backstage version that your target RHDH release uses
2. Upgrade to a specific Backstage version — Bump to an exact Backstage release (e.g., 1.45.3)
3. Check what version I'm on — Discover current @backstage/* versions without making changes
4. Fix issues after a version bump — Resolve breaking changes, moved packages, or build failures after upgrading

Wait for response before proceeding.

| Response | Action | |----------|--------| | 1, "latest", "RHDH", "align" | Follow workflows/full-upgrade.md (RHDH-aligned) | | 2, "specific", "version", number like "1.45" | Follow workflows/full-upgrade.md (user-specified version) | | 3, "check", "current", "what version" | Read references/discover-versions.md and report findings | | 4, "fix", "breaking", "issues", "errors" | Read references/fix-breaking-changes.md and references/migrate-packages.md |

| Reference | Load when... | |-----------|-------------| | references/discover-versions.md | Reading current Backstage versions from a project | | references/determine-target.md | Figuring out what Backstage version to target | | references/bump-deps.md | Running the version bump command | | references/migrate-packages.md | Handling moved/renamed packages | | references/fix-breaking-changes.md | Resolving breaking changes from changelogs | | references/verify-upgrade.md | Verifying the upgrade succeeded | | ../rhdh/references/versions.md | Looking up RHDH → Backstage version mapping |

• All @backstage/* deps align to the target release version
• No packages still reference old names (moved to @backstage-community/*)
• yarn tsc passes with no type errors
• yarn build succeeds
• yarn test passes (if tests exist)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: redhat-developer
• Source: redhat-developer/rhdh-skill
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.