Backstage 1.55 Adds Scaffolder Task Recovery and Removes Deprecated Catalog APIs

The Backstage project has released version 1.55 of its open-source developer portal framework, adding automatic recovery for Software Template tasks that crash or time out. The release also removes a set of deprecated catalog APIs and moves the search module to Elasticsearch 8, so platform teams have several breaking changes to work through before they upgrade.

Task recovery sits behind a new scaffolder.taskRecovery configuration section. When it is enabled, the scaffolder resumes a task from the last completed step, keeps task secrets until the task reaches a terminal state and persists completed step outputs so later steps can read them. The release notes warn that actions used by recovered tasks should be idempotent or use checkpoints, because a resumed task can run an action a second time. The new section replaces three experimental flags, which still work as fallbacks.

The feature responds to a long-standing request. In April 2025, on a GitHub issue tracking scaffolder task retries, Manoj Azad wrote, "Currently, having to re-run the entire scaffolder process can be not only inconvenient but also problematic from a technical standpoint." The 1.55 feature covers tasks interrupted by a crash or time-out, which addresses part of that request.

Workspace serialisation is optional and needs a separate provider module. The new database provider has a 50 MB limit and is intended for development, and the release notes point production installations to the GCP module or a similar external store.

Most of the upgrade work sits in the breaking changes. The catalog backend drops the catalog.enableRelationsCompatibility option, so entity relations now return only targetRef, and it removes the deprecated CodeOwnersProcessor and AnnotateScmSlugEntityProcessor in favour of community modules. The Elasticsearch module now requires Elasticsearch 8.19 or later, although the AWS and OpenSearch providers are unaffected, and custom code that reads raw client responses needs updating. TechDocs strips MkDocs plugins that are not on a built-in allowlist, and teams that need extra plugins must list them under techdocs.generator.mkdocs.dangerouslyAllowAdditionalPlugins. Further breaking changes affect Backstage UI link components, the GitHub repository creation action, incremental ingestion permissions and the Sentry scaffolder action.

Several changes target governance and speed. The scaffolder.requireScmUserCredentials option, first added in the 1.54.6 patch, requires user-provided credentials for supported GitHub, GitLab, Bitbucket and Azure DevOps actions. Permission policies that deny unknown permissions must now explicitly allow scaffolder.template.dry-run to keep template dry runs working. Michael Todorovic, a senior SRE at Veepee, changed the GitLab merge request and push actions to compare files locally. "publish:gitlab:merge-request was taking 5–15 seconds against a self-hosted GitLab," he wrote. "It turned out almost all of that was the action asking GitLab for information it already had." The change cuts API requests for a repository of a few hundred files from roughly 300 to under ten, and a step that took 5 to 15 seconds down to about 3 seconds. Core plugins such as the catalog, search and TechDocs now load their pages only when they render, which reduces the initial app bundle.

Since 15 September, the maintainers have shipped three patch releases. Version 1.55.1 fixed the new backstage-cli pm verify-patches command and TechDocs add-ons on the new frontend system, while 1.55.2 and 1.55.3 fixed how TechDocs handles MkDocs Markdown extension configuration.

The release also lists security fixes in seven packages, including the OIDC and Cloudflare Access auth providers and the proxy backend. The Cloudflare Access provider now requires the application audience in its configuration. The next minor version is already in pre-release, with 1.56.0-next.2 published on 6 October.