How a monthly Backstage upgrade stays routine
A monthly Backstage upgrade stays routine when your team moves every @backstage package together with yarn backstage-cli versions:bump, then applies the template changes the Backstage Upgrade Helper shows between your current version and the target. Partial bumps are what turn a routine release into a debugging session, because packages built against different core versions fail in ways that are hard to trace. Treat the bump and the template merge as one change set, reviewed and tested together.
The release cadence sets your rhythm. Backstage's versioning policy ships the main release line monthly, on the Tuesday before the third Wednesday of each month, and the next release line weekly on Tuesdays. Plan one scheduled upgrade window per month against the main line, and use the weekly next line in a non-production environment to catch breaking changes early. Confirm the exact dates for the current year on the release page rather than calculating them yourself.
Security fixes affect how urgently you must move. The policy says high and critical severity vulnerabilities are backported to releases from the last 6 months where feasible, and other security fixes may be backported. That gives you a window, not a license to wait: if your deployed version falls outside it, a severity fix may only arrive on a newer line, so check which versions are still covered before you decide to skip a month. Backstage is licensed under the Apache License 2.0 (SPDX: Apache-2.0), and the project itself offers no paid edition. Your upgrade cost is therefore your own engineering time, your test environments and any partner work you buy, not a license renewal. Before the first monthly cycle, confirm who on your team reads each changeset, who approves the template merge and who owns a rollback if a release breaks sign-in or the catalog.
What changes between Backstage releases and what you must do
This table compares the kinds of change that arrive with each Backstage release and the work each one creates for your app and backend packages. Read it as a checklist for every monthly bump: most rows end in a specific action you can schedule before the release lands in your repository.
| Change | Impact on your app | Action needed |
|---|---|---|
| versions:bump package move | Moves all @backstage packages to matching versions together, so mixed versions are avoided | Run yarn backstage-cli versions:bump in a dedicated branch and commit the result separately |
| Changeset notes | Release notes list breaking, deprecated and changed APIs for each package | Read changesets for every package you use, including custom plugins, before merging |
| Upgrade Helper template diffs | Shows template file changes between two versions, including config and app structure | Apply the relevant template changes to your app and backend packages by hand, then compare the diff |
| Node.js 22 and 24 support as of 1.46.0 | Backstage supports exactly two adjacent even-numbered Node.js releases | Confirm your runtime, Docker base image and CI use Node.js 22 or 24 before upgrading |
| Security backports for high and critical issues | High and critical vulnerabilities are backported to releases from the last 6 months where feasible | Track the release line you run and plan to stay within six months of the latest release |
| Latest release facts | v1.55.3 was published September 29, 2026, and 1.56.0 is in the next release line | Confirm which line you target: main monthly or next weekly, then test against that version |
What to back up and inventory before you bump
A version bump changes every @backstage package at once, and the Upgrade Helper diff is only useful if you can compare it against a known starting point. The items below give you a rollback path, a map of what you must re-test, and a staging environment that behaves like production.
Backup of each plugin database
Backstage gives each backend plugin its own logical database through Knex, so a backup of the PostgreSQL instance must cover every plugin schema, not only the catalog. Take a point-in-time snapshot and confirm you can restore it into a scratch instance. Plugins that run migrations on startup can alter their tables during the bump, so a restore test is the only proof the backup works.
Copy of app-config and secret references
Save the current app-config files for every environment, along with the names and locations of the secrets they reference. Store secret references, not secret values, in the repository, and record which environment variables each config key expects. Upgrades rarely remove config keys, but new defaults and renamed options can change behavior silently, so a dated copy lets you diff what changed.
Inventory of custom plugins and patches
List every internal plugin, every local package patch, and every dependency pinned in resolutions. Note which ones import APIs from @backstage packages that the release may deprecate, such as legacy backend packages. This list tells you which parts of the Upgrade Helper output will touch your own code, and which packages need owners to review their changes before the monthly release.
Third-party plugins and their versions
Record the exact version of each community or vendor plugin you install, with its source repository and maintainer. Plugins that depend on a specific @backstage release line can break when the core moves, and some have moved to a different repository or package name. A pinned list lets you check compatibility per plugin and decide whether an upgrade waits for a plugin release.
Staging that mirrors production
Build a staging instance with the same authentication provider, sign-in resolvers, and caching backend as production, whether Redis, Memcache, Infinispan or in-memory. Auth and cache behavior are the most common surprises after a bump, and a staging setup that uses guest access or a different cache will hide them. Confirm that staging can reach the same catalog sources and integrations.
Git tag and image digest for rollback
Before you start, record the current Git tag or commit and the exact container image digest in production. A tag can be moved, so the digest is the reliable reference for rolling back a deployment. Keep the previous image in your registry until the new release has run cleanly for a full cycle, and write the rollback steps down before the window opens.
The monthly upgrade sequence with checks and rollback points
This sequence moves all @backstage packages to a target release in one pass, checks each change against staging, and leaves a clear revert point before anything reaches production. Each step names the output that tells the team it can move on.
Create a release branch from main
The platform engineer who owns the portal creates a dedicated branch from the current production commit, named for the target Backstage release. Before touching any file, they record the current lockfile hash, the running container image tag and the staging database snapshot identifier, so each rollback point is known in advance. Done means the branch exists, the baseline values are written in the change ticket, and CI passes on the unchanged code.
Run versions bump to the target release
From the repository root, run yarn backstage-cli versions:bump with the target release line, which moves every @backstage package in the app and backend to matching versions. Confirm the target against the Backstage GitHub releases page and the versioning policy, because the main line ships monthly and the next line ships weekly. Done means package.json files and yarn.lock show a single consistent Backstage version across the workspace, with the diff committed as its own commit.
Resolve dependency conflicts and duplicates
Run the package manager install and inspect any peer dependency warnings or duplicate @backstage packages that the bump leaves behind. Pin or align third-party plugins that do not yet support the target release, and record each exception with its owner so it is not forgotten. Done means the install completes without unresolved peer errors, and the team has a written list of any plugins held back.
Read changesets and release notes for the target
Read the changesets and release notes for every release between your current version and the target, paying attention to breaking changes, deprecations and removed packages. Note any change that touches your own plugins, auth configuration, catalog processors or scaffolder actions, since those need manual work. Done means each breaking item has a matching task on the branch or a documented reason it does not apply.
Apply Upgrade Helper template changes
Open the Backstage Upgrade Helper, select your current and target versions, and apply the template changes to the app package and the backend package by hand, comparing each file against your customized version. Keep configuration keys, custom routes and local plugin wiring intact while adopting new defaults. Done means each changed file has been reviewed, the diff is limited to intended changes, and the reviewer has signed off on the pull request.
Run type checks, unit tests and the build
Run the workspace type check, the unit test suite and the production build in CI, on the same Node.js version your image uses. Any failure in a custom plugin is fixed on the branch rather than skipped. Done means all three jobs pass on a clean checkout, and the build artifact is tagged with the candidate version so it can be traced later.
Verify staging against PostgreSQL and sign-in
Deploy the candidate to staging with a restored copy of the production PostgreSQL data, so migrations run against realistic state. Confirm that sign-in works with each configured provider, that the sign-in resolvers still map every provider to the same catalog identity, and that guest access stays disabled. Then check catalog ingestion logs for new errors and confirm that a scaffolder template run completes end to end. Done means these checks are recorded with the staging image tag, and any failure blocks promotion.
Promote with a documented rollback plan
Before promotion, record the production image tag, the lockfile commit and a fresh database backup as the three rollback points, and confirm with the operations owner that the backup restores. Promote the candidate, then watch sign-in, catalog and scaffolder health after the release. If a check fails, revert the image tag first, redeploy the previous lockfile if the code change must be undone, and restore the database only when a migration has altered data in a way the older code cannot read. Done means the release is live, the rollback steps are rehearsed in the runbook, and the change record is closed.
How to test before release and roll back safely
Treat the test set as the release gate. A bumped Backstage app is not ready until catalog processing, sign-in with resolver mapping, TechDocs builds, search, Kubernetes views and your custom plugin smoke tests all pass against a staging copy that uses the same database engine, auth providers and plugin list as production. Run the catalog first, because a bump that changes entity processing can silently drop entities or orphan ownership. Then sign in through each configured provider and confirm that every provider resolves to the same catalog identity, since a changed resolver or a renamed claim often shows up here before anywhere else. Build a sample of TechDocs sites, query search for known entities, open the Kubernetes tab for a few services, and exercise each internal plugin's main page and one API call. Keep the checklist in version control so each monthly run repeats the same steps.
Confirm your rollback path before you start the bump, not after a failed release. A rollback is clean only when database migrations are reversible or you hold a restore point taken immediately before the upgrade. Plugins each keep their own logical database, so check every plugin schema the app writes to, not only the catalog. Ask your platform team to confirm how they take and test a restore of the PostgreSQL instance, and record how long a restore takes in your environment. Keep the previous container image tag and the previous lock file so you can redeploy the old code against a restored database. Do not assume that a schema change which seems additive can be undone by reverting code.
Do not use guest access as a shortcut in testing. The authentication documentation advises against offering guest access in production, so a test that passes only because guest sign-in is enabled proves nothing about the real sign-in path. Test with the same provider configuration, resolver and sign-in flow that users will use, using test accounts in your staging identity directory. If a test cannot run without guest access, fix the test setup rather than changing the production configuration. Where a release candidate passes all checks, record the results and the restore point together so an auditor or incident responder can see what was proven before the change went live.
Monthly bump, skipped releases or Node.js change: which path applies
This is the lowest-effort path. Your app tracks the main release line, which Backstage ships monthly on the Tuesday before the third Wednesday of each month. If you upgrade once per release and never skip one, the changes in each bump are small and the Upgrade Helper diff is usually limited to the packages and config your app already uses. Work should fit inside a routine sprint once your team has run the process a few times.
- Run the bump on a fixed schedule: Pick a day after each main release, so changes are reviewed while the diff is still small.
- Use versions:bump for all @backstage packages: Move them together with
yarn backstage-cli versions:bumprather than editing versions one by one. - Read the changesets first: Each release note lists what changed in the packages your app depends on.
- Apply template changes from the Upgrade Helper: Only touch the app and backend files that the helper marks as changed for your versions.
- Keep the change in its own pull request: Separate it from feature work so a regression is easy to isolate.
Before you merge, confirm that your test suite, build and a staging sign-in and catalog check pass on the new version.
Teams on the next release line take a weekly cadence, shipped on Tuesdays. This path suits teams that want early access to changes or that maintain plugins that depend on upcoming APIs. The work per bump is still small, but the frequency is higher, so the effort recurs more often. The main cost is the time spent on review, not the upgrade itself.
- Accept more frequent recurring review: Each weekly release needs a changeset read and a test run, so plan a standing slot for it.
- Batch small bumps when possible: If a weekly release changes nothing your app uses, record that and skip the merge until the next change that matters.
- Expect more churn in unstable areas: Next-line changes can alter APIs that the main line has not yet adopted, so test plugin code closely.
- Confirm the stability you need: Ask whether your organization can accept next-line changes in production or only in a staging environment.
- Track the main line in parallel: Know when a next-line change becomes part of the monthly main release, so you can plan the move.
Check whether your organization is comfortable running next-line builds in production and whether your custom plugins are tested against them.
This path applies when your app has missed one or more monthly releases, or has drifted far enough that a single bump produces a large diff. The work level rises with the number of releases skipped, because deprecations, package moves and framework changes stack up. Backstage's versioning policy backports high and critical severity fixes to releases from the last six months where feasible, so an app older than that window may not receive those fixes in place and should be moved forward soon.
- Check your version against the support window: Confirm which release lines still receive backports before deciding how urgent the move is.
- Step through versions when the gap is large: Upgrade in stages so each diff is reviewable, rather than applying one very large change.
- Plan for deprecations and system changes: Older apps may depend on packages or patterns that later releases removed or replaced.
- Use sibling topics for heavy catch-up work: Bringing an app that has skipped a year or more of releases up to date is covered on the catch-up page, which also addresses when a rebuild is cheaper.
- Compare the cost of rebuilding: A badly drifted app may take less effort to recreate from a current template.
Confirm the gap size and your support window before estimating effort, and ask a partner to scope the catch-up work in writing.
A Node.js change is a separate job from a version bump, and it can happen alongside one or on its own. Backstage supports exactly two adjacent even-numbered Node.js releases, which are Node.js 22 and 24 as of Backstage 1.46.0 according to the versioning policy. When the supported pair moves, your runtime, container base images, CI runners and native modules must all move with it. Treat this as its own change with its own test pass.
- Confirm the supported pair for your release: Check the versioning policy before choosing a target runtime.
- Align every runtime location: Update local tooling, Docker base images and CI images together so builds match.
- Test native modules: Packages with compiled code may need rebuilding or replacing on the new runtime.
- Schedule the change apart from routine bumps: Mixing a runtime change into a monthly bump makes failures hard to attribute.
- Follow the dedicated Node.js topic: The sibling page on moving a Backstage app to a newly supported Node.js release covers matching images, CI and when older releases are dropped.
Before you start, confirm which Node.js releases your Backstage version supports and whether any of your plugins pin a runtime version.
Custom plugins are often the step that decides how long an upgrade takes. Core APIs change between releases, and your internal plugins may import packages that were deprecated or moved. This path applies to any team that maintains its own backend or frontend plugins, whether or not the app itself is current. The effort depends on how many plugins you own and how many core APIs they use.
- Inventory your plugins and their imports: List each internal plugin and the @backstage packages it depends on.
- Check for deprecated packages: Some older backend packages have been superseded, so plugins may need new imports or extension points.
- Test plugins against the new release: Run each plugin's own tests after the bump, not only the app's tests.
- Assign an owner for each plugin: Someone must own the upgrade work, or it stalls after the first failure.
- Use the dedicated compatibility topic: The sibling page on keeping custom plugins compatible across upgrades covers extension points, testing and ownership in more depth.
Before a bump, confirm which of your plugins depend on changed APIs and who will fix them if they break.
What makes a Backstage upgrade take longer
This table lists the factors that most often stretch a monthly versions:bump upgrade beyond its routine length, with the effect each has on effort and what to check in your app before you start. Read it before estimating a sprint, because the drivers that matter most are usually in your own code and configuration rather than in the upstream release notes.
| Driver | Effect on effort | What to check |
|---|---|---|
| Custom plugins that depend on core APIs | Each internal plugin that imports changed or deprecated core packages needs its own code changes and tests, often the largest share of the work | List every internal plugin, the @backstage packages it imports, and whether any use deprecated APIs or the legacy backend packages |
| Number of third-party plugins | Each community plugin may lag the core release line, so its version must be bumped, pinned or replaced before the app builds | Compare each plugin's peer dependency range with the target Backstage version and note any that moved repositories |
| Local patches to @backstage packages | Patches applied to upstream packages can conflict with template changes or with the new release, and may need rework or removal | Search the repository and patch files for patched @backstage packages and confirm whether each fix is still needed upstream |
| Database size and migration runs | Larger catalog and plugin databases take longer to migrate, and a failed migration can block the release window | Measure the size of each plugin database, run migrations against a recent copy, and time the run in a non-production environment |
| Number of authentication providers | Each provider configuration and sign-in resolver must be re-tested, since provider modules and resolver behavior can change between releases | Confirm every provider in use, its resolver, and that all providers still resolve to the same identity after the upgrade |
| Custom scaffolder actions | Custom actions depend on scaffolder APIs that can change, and template behavior must be retested end to end | List each custom action, its imports, and the templates that call it, then run each template against a test repository |
| Search engine configuration | Search engine changes, including Elasticsearch version support, can require reconfiguration and a reindex that adds time to the release | Record the search engine and version in use, confirm it is supported by the target release, and plan a reindex if the engine changes |
| Whether CI covers the app | Without build, lint, type-check and test coverage, regressions surface in staging or production, which lengthens the upgrade and the rollback | Confirm CI builds the app and backend, runs unit tests for custom plugins, and includes a smoke test of sign-in and catalog loading |
Questions teams ask before a Backstage upgrade
What does a Backstage upgrade cost and what drives the price?
The cost depends mostly on how far your app has drifted from the template and how much custom code it carries. The project's upgrade tooling is free, since Backstage is open source under the Apache License 2.0 with no paid edition from the project itself, so your spend goes to people and test environments. Cost components are internal engineer time, any partner time, CI and staging capacity, and review effort. The one-time cost is the first catch-up. The recurring cost is the monthly bump, which grows with the number of custom plugins and integrations you maintain. When you request a quote, ask for the written scope, the list of custom packages covered, the release line targeted, and what testing is included.
How long does a monthly Backstage upgrade take?
Duration is set by how many packages you own and how many template changes land in that release. The main release line ships monthly, on the Tuesday before the third Wednesday of each month, so the cadence is predictable even though the effort is not. A clean app with no custom plugins usually moves quickly. Apps with several internal plugins, custom scaffolder actions or changed backend modules need more review and testing. Confirm the duration against your own build and test suite, since no fixed figure applies to every app.
What does the upgrade need from our internal team?
The work needs an owner who understands your app, someone who can review the changesets and template diffs, and an engineer who can run the portal in a non-production environment. Expect the team to decide which template changes to accept, resolve merge conflicts in custom code, and sign off on test results. Also plan for access to your CI pipeline, container registry, identity provider test tenant and catalog data. If nobody on the team has modified the app before, the first upgrade will take longer than later ones.
Can our own team run the monthly bump in-house?
Yes, a team that owns its Backstage code can run the monthly bump in-house. The core commands are yarn backstage-cli versions:bump and the Upgrade Helper, which shows template changes between versions. The harder part is judgment: reading changesets, deciding which deprecations affect your plugins and keeping custom code compatible. Teams that do this in-house usually set a fixed monthly slot, keep a staging portal that mirrors production, and track which release line they run. A partner is more useful for the first catch-up or for a large plugin estate.
How do we handle a security backport for Backstage?
The versioning policy says high and critical severity vulnerabilities will always be backported to releases from the last 6 months if feasible, and other security fixes may be backported. That means a security fix may arrive as a patch on your current line, which you can apply without waiting for the next monthly bump. Keep your app on a release inside that window, watch the GitHub releases page, and test patch releases in staging before production. Confirm your process for emergency patches with whoever owns your change management.
What happens if a Backstage release breaks sign-in?
Sign-in breaks usually come from changed provider configuration, sign-in resolver behavior or auth package APIs, so the first check is the authentication configuration in your app. Backstage ships 19 built-in authentication providers, and the documentation advises resolvers so every provider resolves to the same identity and no guest access in production. Keep a rollback path by retaining the previous container image and lockfile, and test sign-in with each provider in staging before release. If the break reaches production, roll back the image first, then fix the configuration in staging.
Should we wait for a major release line before upgrading?
Waiting for a long gap increases the work, because the template and API changes accumulate. Backstage ships a main release line monthly and a next release line weekly, so you can track changes early by reading the next line in a test environment. Staying close to the main line keeps each upgrade small. Ask your partner or internal owner how they plan to handle the next line and what they will test before adopting it.
How DeployOpen works on this
DeployOpen plans and delivers Backstage upgrades inside your own infrastructure, starting from a written scope for your app and backend packages. We work through the monthly versions:bump routine, the Upgrade Helper template changes and your test suite, then hand over a documented, repeatable process your team can run without us.
How we scope
- We record your current Backstage version, installed plugins and the custom plugins your app and backend depend on.
- We agree the target release line, whether main or next, and which upgrade steps are in or out of the written scope.
- Engagements are fixed-scope, with deliverables and timelines confirmed in writing before any upgrade work begins.
How we build
- We run versions:bump in a branch, review each changeset, and apply Upgrade Helper template changes to the app and backend packages.
- We resolve breaking changes and deprecations found in the diff, and record every change that needed a manual decision.
- We run your existing tests, build and smoke checks against a staging environment that mirrors your production configuration.
How we hand over
- You receive the upgrade branch, a change log mapping each applied change to the changeset it came from, and test results.
- We document the monthly upgrade runbook so your team can repeat versions:bump, review changesets and run checks on its own.
- Handover includes a short review session covering the decisions made, open items and the checks to run before each release.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers, scoped to your release cadence.
- Retainers can cover each monthly main release or weekly next release, with the same change log and test evidence.
- Ask us to confirm the support hours, response terms and included upgrade work in writing before you sign any retainer.
