Backstage 1.55: Advancing Developer Portals with Task Recovery and Performance Optimizations

The open-source community behind Backstage, the CNCF-graduated developer portal framework, has officially released version 1.55. This update marks a significant milestone in the project’s maturity, introducing long-awaited resilience features for software templating, major architectural cleanups, and performance enhancements designed to scale with the needs of large enterprise platform teams.

While the release offers powerful new capabilities, it also brings a substantial list of breaking changes that will require platform engineers to dedicate significant time to migration and testing. From the shift to Elasticsearch 8 to the tightening of security and governance protocols, version 1.55 is a transformative update that prioritizes long-term stability over backward compatibility.

Main Facts: The Core of Version 1.55

The flagship feature of the 1.55 release is the introduction of automatic task recovery for the Scaffolder. For years, a common pain point for Backstage users has been the brittleness of software templates; if a long-running process failed or timed out, developers were often forced to restart the entire workflow from scratch.

By introducing the scaffolder.taskRecovery configuration, the Backstage team has enabled a checkpoint-style system. When enabled, the scaffolder now:

Resumes from the last successful step: Instead of starting from step one, the system picks up where it left off, significantly reducing wasted compute and time.
Maintains Context: The system preserves task secrets until the entire process reaches a terminal state and persists output from completed steps, allowing subsequent steps to access necessary data.
Replaces Experimental Flags: This new implementation consolidates three previously separate experimental flags, though they remain active as temporary fallbacks to ensure a smooth transition.

However, the maintainers have issued a critical warning: actions must be idempotent. Because the system resumes from the last completed step, there is a risk that a partially executed but interrupted action could be triggered a second time. Developers are encouraged to design their custom scaffolder actions with idempotency in mind or leverage checkpointing mechanisms to ensure consistency.

Chronology: The Road to 1.55 and Beyond

The development of the 1.55 release has been a multi-month effort aimed at addressing technical debt and scaling bottlenecks.

April 2025: User Manoj Azad opened a pivotal GitHub issue (#22590) highlighting the operational friction caused by the inability to retry scaffolder tasks. His input catalyzed the work that eventually became the task recovery feature.
Mid-2025: Throughout the summer, the maintainers focused on deprecating older catalog APIs and refining the Scaffolder’s permission model.
September 15, 2025: The initial 1.55.0 release was cut. Shortly thereafter, the team shifted into a rapid patch cycle.
Late September/Early October: The release of versions 1.55.1, 1.55.2, and 1.55.3 addressed early feedback, including fixes for the backstage-cli and refinements to TechDocs Markdown configurations.
October 6, 2025: The community began testing the 1.56.0-next.2 release, signaling that the project remains on an aggressive, high-velocity release cadence.

Supporting Data: Infrastructure and Performance Shifts

Version 1.55 is not just about new features; it is a major housekeeping release. Several key architectural shifts have been implemented to modernize the stack:

Elasticsearch 8 Migration

The search module has been officially moved to Elasticsearch 8. This upgrade requires that installations use Elasticsearch 8.19 or later. While AWS and OpenSearch providers remain largely unaffected, custom code that interacts with raw client responses will likely break and require immediate refactoring.

Database and Storage Constraints

Workspace serialization—a key component of the new recovery feature—is now optional and requires a separate provider module. The team has provided a default database provider, but it is strictly intended for development environments, as it carries a 50 MB limit. For production, the maintainers explicitly recommend utilizing the GCP module or other robust, scalable external storage solutions.

Performance Wins

A standout improvement came from the community-driven optimization of GitLab actions. Michael Todorovic, a senior SRE at Veepee, identified that the publish:gitlab:merge-request action was performing excessive API round-trips for data it already possessed. By optimizing the logic to compare files locally, the action saw a massive reduction in API overhead—dropping from roughly 300 requests to fewer than 10 for a standard repository. The result is a speed increase from 15 seconds down to approximately 3 seconds, a change that will significantly improve the developer experience for teams relying on GitLab.

Furthermore, core plugins including the catalog, search, and TechDocs have been optimized to load only upon rendering. This "lazy-loading" approach reduces the initial application bundle size, leading to faster page loads and a more responsive interface for end-users.

Official Responses and Governance

The 1.55 release reflects a growing emphasis on security and governance within the Backstage ecosystem.

The scaffolder.requireScmUserCredentials option, introduced in the previous 1.54.6 patch, has been further integrated into the core workflows. It mandates that users provide explicit credentials for GitHub, GitLab, Bitbucket, and Azure DevOps, preventing the insecure use of hardcoded or overly permissive service accounts.

Additionally, the project has tightened its stance on TechDocs. To improve security and stability, the system now strips out any MkDocs plugins that are not on a strictly maintained, built-in allowlist. Organizations that require custom plugins must now explicitly opt-in by configuring techdocs.generator.mkdocs.dangerouslyAllowAdditionalPlugins. This is a deliberate "guardrail" design, forcing platform teams to take responsibility for the security posture of their documentation pipelines.

Implications: Preparing for the Upgrade

For platform teams, the transition to 1.55 is a non-trivial undertaking. The sheer volume of breaking changes demands a careful migration strategy:

Catalog Cleanup: The removal of catalog.enableRelationsCompatibility and the sunsetting of CodeOwnersProcessor and AnnotateScmSlugEntityProcessor will require updates to your catalog configuration. These processors have been moved to community-managed modules, which you must now adopt to maintain existing functionality.
Permission Policy Updates: With the enforcement of scaffolder.template.dry-run permissions, teams that use granular permission policies will need to audit their code to ensure that dry-run functionality is not inadvertently blocked.
UI/UX Disruptions: Changes to UI link components and the Sentry scaffolder action mean that custom front-end components and error-tracking integrations should be thoroughly smoke-tested in a staging environment before being deployed to production.
Security Patches: The release includes critical security fixes for the OIDC and Cloudflare Access auth providers, as well as the proxy backend. The change to the Cloudflare Access provider (now requiring an application audience) is mandatory and will result in authentication failures if neglected.

Conclusion: A Maturity Milestone

Backstage 1.55 represents the project’s ongoing evolution from a "cool experimental tool" to a hardened, enterprise-grade platform. While the breaking changes are extensive, they are indicative of a project that is cleaning up its API surface and establishing rigorous standards for security and performance. By addressing the long-standing request for task recovery and optimizing high-latency API calls, the maintainers have provided tools that directly impact the daily productivity of software engineers.

Platform teams are advised to treat the 1.55 upgrade as a high-priority project. Given the complexity of the migration, it is recommended to utilize the backstage-cli tools provided in the latest patches to verify existing setups and catch potential regressions before they reach the end-user. As the project looks toward 1.56 and beyond, the focus will likely remain on consolidating these gains and ensuring that the developer portal experience remains both performant and secure at scale.