If your platform team runs Backstage, version 1.55 has one feature people have wanted for a long time and a handful of changes that will break things if you upgrade without reading the notes. This is a short guide to both.
Template runs can finally pick up where they stopped
Anyone who has used Backstage software templates in anger has seen this. A developer clicks "create service", the template creates the repo, sets up the pipeline, then times out halfway through registering it in the catalog. Now you have half a service, a confused developer and a ticket.
1.55 adds opt-in task recovery through a new scaffolder.taskRecovery config section. A task that crashes or times out can resume from its last completed step. It keeps its secrets until it finishes, and it saves the outputs of completed steps so later steps can use them. The new section replaces three experimental flags, which still work for now.
There is one catch, and it is important. A resumed task can run an action twice. If one of your custom actions creates a repo, sends a Slack message or opens a ticket, make sure running it again does no harm. Otherwise recovery will turn one stuck task into two GitHub repos.
Saving workspace state is optional and needs a separate module. The new database provider has a 50 MB limit and is meant for development. In production you will want the GCP module or a similar external store.
Things that will break
The catalog option catalog.enableRelationsCompatibility is gone. Entity relations now only return targetRef. Any plugin or script that reads the old relation fields needs updating.
The Elasticsearch search module now needs Elasticsearch 8.19 or later. If you run an older cluster, upgrade it first. The AWS and OpenSearch providers are not affected.
TechDocs now strips any MkDocs plugin that is not on a built-in allowlist. If your docs use extra plugins, list them under techdocs.generator.mkdocs.dangerouslyAllowAdditionalPlugins, or your docs will quietly render without them. The word "dangerously" in that setting is deliberate. Plugins run code at build time, so only add ones you trust.
The deprecated CodeOwnersProcessor and AnnotateScmSlugEntityProcessor have been removed in favour of community modules. There are also smaller changes to Backstage UI link components, the GitHub repository creation action, incremental ingestion permissions and the Sentry scaffolder action.
How we would roll it out
Upgrade a staging instance first and run your five most-used templates end to end. Search the codebase for the removed processors and the old relations option. Check which MkDocs plugins your docs actually use. Then turn on task recovery for one template whose actions you know are safe to repeat, and widen it from there.
Budget half a day for it, on a weekday, with the changelog open in another tab.
