v1.53.0

These are the release notes for the v1.53.0 release of Backstage.

A huge thanks to the whole team of maintainers and contributors as well as the amazing Backstage Community for the hard work in getting this release developed and done.

Highlights

BREAKING: Removed deprecated SSE transport from MCP actions

The deprecated Server-Sent Events (SSE) MCP transport has been removed from @backstage/plugin-mcp-actions-backend. MCP clients must use the Streamable HTTP endpoint at /api/mcp-actions/v1 or a configured named-server endpoint.

BREAKING: Configuration schemas now resolve imported types

Configuration schemas declared in TypeScript now resolve and validate imported types in @backstage/config-loader, instead of treating them as unconstrained values. Invalid imports now cause schema loading to fail. This may surface previously undetected schema issues in plugins that import types in their config.d.ts files.

BREAKING: Stricter OAuth redirect URI and CIMD allowlist matching

The OAuth redirect URI and client ID metadata document allowlists in @backstage/plugin-auth-backend now match patterns against each URL component separately instead of against the full URL string. Wildcards no longer match across the host and path boundary, patterns must include an explicit protocol and are otherwise rejected as invalid configuration instead of being silently ignored, and redirect URIs that contain embedded credentials are always rejected.

A wildcard port also no longer implicitly matches every path: a pattern such as http://localhost:* now only matches the root path. Use http://localhost:*/* to allow any port and any path. The built-in loopback defaults have been updated accordingly, so this only affects explicitly configured patterns.

BREAKING ALPHA: Catalog entity page migrated to BUI

The new frontend system Catalog entity page has been migrated to Backstage UI components with several breaking alpha changes in @backstage/plugin-catalog and @backstage/plugin-catalog-react:

The entity page now uses a BUI page header with entity tags, title, metadata, favorite and context-menu actions, and Catalog-composed navigation. Existing alpha opaque entity header customizations continue to render through a temporary per-entity legacy fallback. Migrate those customizations to the new BUI-ready entity header layout extension point.
The entity context menu has been migrated to BUI with Remix icons. The EntityContextMenuItemBlueprint now outputs menu item data instead of a rendered MUI element. The icon type is now IconElement — we recommend using Remix icons.
A new alpha entity header layout extension point has been added, providing Catalog-composed tabs and the active tab ID for custom entity headers. The existing opaque entity header extension point is deprecated.

New translation keys have been added: entityLabels.systemLabel, entityLabels.domainLabel, entityLabels.partOfLabel, and entityContextMenu.moreButtonAriaLabel (default changed from more to More actions). Apps that provide Catalog translations should add entries for these new messages.

BREAKING: Removed legacy proxy agent bootstrap

The deprecated bootstrapEnvProxyAgents export has been removed from @backstage/cli-common, along with the global-agent and undici dependencies. The versions:bump command in @backstage/cli-module-migrate and newly created apps from @backstage/create-app no longer bootstrap legacy proxy agents either. Use Node.js built-in proxy support by setting NODE_USE_ENV_PROXY=1 alongside your HTTP_PROXY/HTTPS_PROXY/NO_PROXY environment variables instead. See the corporate proxy guide for details.

Contributed by @jonkoops in #33444

BREAKING: Replaced Optic with oasdiff for OpenAPI tooling

@useoptic/optic and @useoptic/openapi-utilities have been replaced with oasdiff in @backstage/repo-tools for OpenAPI breaking change detection. To migrate, remove @useoptic/optic from your root package.json and install the oasdiff CLI — see oasdiff installation for instructions.

The package schema openapi diff command now uses oasdiff under the hood. The --since, --json, and --ignore flags continue to work, but the output format has changed to match oasdiff's native output. The repo schema openapi diff command now automatically detects packages with a changed src/schema/openapi.yaml — packages no longer need a "diff" script in their package.json.

The package schema openapi init and repo schema openapi test commands have been removed. Runtime validation is still available via wrapServer from @backstage/backend-openapi-utils/testUtils. The previously deprecated wrapInOpenApiTestServer function has also been removed from @backstage/backend-openapi-utils — use wrapServer instead.

Contributed by @jonkoops in #34452

Backstage UI updates

This release includes several additions to Backstage UI:

Breadcrumbs: A new breadcrumbs prop has been added to PluginHeader that renders a navigation breadcrumb trail, visually hiding the plugin title when breadcrumbs are present. Breadcrumbs collapse middle segments when five or more are present and show tooltips for truncated text. On the framework side, a useBreadcrumbEntries hook, BreadcrumbEntry component, and BreadcrumbsRegistryProvider have been added for managing breadcrumb trails across plugin pages using the new frontend system. Sub-pages created with PageBlueprint now automatically contribute to PluginHeader breadcrumbs without extra wiring.

Contributed by @clairep94 in #34587, #34588, and #34682

New components: A TextAreaField component has been added for multi-line text input, following the same conventions as TextField with support for a label, secondary label, and description. Contributed by @vanessaliu in #34611.

Re-exports: The types Selection, SortDirection, and Key (type-only), and the runtime export Focusable from react-aria-components are now available directly from @backstage/ui, avoiding version mismatches. Contributed by @sspadotto in #34540.

Check the BUI Changelog for more details.

Database-backed user settings storage

A new @backstage/plugin-app-module-user-settings frontend module has been added that provides database-backed user settings storage. When installed, it overrides the default browser local storage with the user settings backend, enabling settings to persist across devices and sessions. Newly created apps from @backstage/create-app now include this module out of the box.

Comma-separated `BACKSTAGE_ENV` for config stacking

The BACKSTAGE_ENV environment variable in @backstage/config-loader now supports comma-separated values, allowing multiple environment-specific configuration files to be loaded and stacked at startup. For example, setting BACKSTAGE_ENV=e2e-test,production will load app-config.e2e-test.yaml and app-config.production.yaml in addition to the base app-config.yaml, with later environments taking priority. Local override files (.local.yaml) are always loaded after all non-local files.

Contributed by @jabrks in #34498

Azure DevOps webhook ingress

A new HTTP POST webhook ingress endpoint has been added to @backstage/plugin-events-backend-module-azure for Azure DevOps events, matching the pattern established by the GitHub events module. The ingress endpoint is only registered when events.modules.azureDevOps.webhookSecret is configured, and incoming requests are validated against the x-ado-webhook-secret header using timing-safe comparison.

Contributed by @rishim-personal in #34691

Token revocation support for CIMD clients

Token revocation support has been added for clients using client ID metadata documents (CIMD) in @backstage/plugin-auth-backend. The /v1/revoke endpoint is now available whenever dynamic client registration or CIMD are enabled, and is advertised through revocation_endpoint in the OpenID provider configuration.

Contributed by @djamaile in #34779

CIMD promoted to stable configuration

Client ID Metadata Documents (CIMD) in @backstage/plugin-auth-backend have been promoted to the stable auth.clientIdMetadataDocuments configuration key. The previous auth.experimentalClientIdMetadataDocuments key remains supported as a deprecated alias. Dynamic Client Registration now logs a deprecation warning when enabled — users should migrate to CIMD. Newly created apps from @backstage/create-app now use the stable CIMD configuration by default and no longer advertise Dynamic Client Registration.

Contributed by @djamaile in #34810

Redis cache store connection options

The connection config option for the Redis cache store in @backstage/backend-defaults now accepts either a string URL or an object with additional connection options passed directly to the underlying client. This allows configuring options like pingInterval without needing dedicated config fields. For clustered Redis, the connection object properties are merged into cluster defaults.

Contributed by @AlexandruCatalinPitaLSEG in #34337

Additional fixes and improvements

Fixed the TechDocs reader requesting documentation metadata in a tight loop when the request fails permanently (e.g. 404), which previously flooded the backend with requests and caused the page to flicker. Contributed by @officialasishkumar in #34356.
Fixed DatabaseTaskStore.list returning totalTasks as a string on PostgreSQL, which caused the list-scaffolder-tasks action to fail output validation. Contributed by @mitsukado-shinagawa in #34479.
Fixed Bitbucket Cloud and Bitbucket Server hosts not rendering the correct repository and branch picker fields in the Scaffolder. Contributed by @sikehish in #34111.
Fixed a crash when exporting the catalog with unset filters. Contributed by @lexhuismans-wk in #34745.
Fixed a regression where EntityTypePicker's initialFilter prop was being cleared when used alongside EntityKindPicker inside EntityListProvider.
Fixed scheduled tasks that were initially registered with a manual trigger and later re-registered with a duration or cron cadence never being scheduled to run.
Fixed duplicate React key warnings in the ownership card when different entity kinds share the same type, and in TechDocs when documentation entities share a name across different namespaces or kinds.
Fixed the published configuration schema in @backstage/plugin-kubernetes-react referencing a file excluded from the package, which caused configuration schema extraction to fail. Contributed by @dyatko in #34721.
Fixed compatibility with yeoman-environment v4+, which is ESM-only, in @backstage/plugin-scaffolder-backend-module-yeoman. Contributed by @Elhefes in #33623.
Fixed the default fetch API to support discovery endpoints that only define an internal target.
Fixed TechDocs pages sometimes rendering blank due to sanitizer hooks registered by other plugins. Contributed by @Dasmat13 in #34811.
Fixed the table filters sidebar rendering a stray 0 when no filters are configured. Contributed by @ATKasem in #34842.
Fixed an issue where two "Notifications" links were displayed in the sidebar for newly created apps. Contributed by @apc-kamezaki in #34815.
Fixed MySQL test database failures in @backstage/backend-test-utils by pinning the Docker image to mysql:8.4 and replacing a startup flag removed in MySQL 8.4.
Pinned @types/node to 22.20.0 in the @backstage/create-app seed lockfile to prevent @types/[email protected] from breaking tsc:full builds.
Added support for AWS PrivateLink for Amazon S3 in @backstage/backend-defaults. Contributed by @zcmander in #34467.
Added an optional prompt setting for Auth0 authorization requests — set it to auto to let Auth0 determine whether the user needs to be prompted. Contributed by @jroebu14 in #34643.
Added screen_hint and login_hint parameter forwarding for the Auth0 authentication provider, enabling invitation flows that direct users to the signup screen and pre-fill the email field. Contributed by @UsainBloot in #34817.
Added support for passing custom flags to embedded postgres processes via backend.database.connection.flags.postgres and backend.database.connection.flags.initdb configuration. Contributed by @mtlewis in #34675.
Added a default implementation for the connections service so backend modules can depend on it without requiring apps to explicitly install the connections service factory. Contributed by @neoreddog in #34769.
Extension if predicates now support specifying an action attribute in the permission reference using the # separator (e.g. catalog.entity.read#read).
The shared ESLint configuration now reports unused imports in config.d.ts configuration schema files, catching stray imports that could break schema loading for published packages. Contributed by @dyatko in #34722.
Migrated the CopyTextButton component from Material-UI to Backstage UI. Contributed by @samarthsinh2660 in #32855.
Improved caching for Module Federation remote builds by extracting dependencies into separate content-hashed chunks.
Increased generated frontend static asset filename hashes to 12 characters to reduce collision risk across long-lived cached builds.
Package preparation now converts TypeScript configuration schemas to separate JSON files.
Improved readability of the AWS S3 URL parser by splitting the monolithic regex into two separate patterns with named capture groups.
Added an option to prevent duplicate widget additions in the homepage and added an empty state for the Add Widget dialog. Contributed by @karthikjeeyar in #31323.
Added support for wildcard plugin entries in frontend discovery endpoints, matching the backend discovery behavior.
Custom catalog entity kinds are now included in the search page kind filter.
The TechDocs plugin now automatically adds the Documentation result type to the Search page when it is installed, and the Search page no longer shows the Documentation result type unless a plugin provides it.
Configuring userGroupMember.path together with user.filter in @backstage/plugin-catalog-backend-module-msgraph is now rejected with a configuration error, as the two options are mutually exclusive.
Added a title field to connection auth methods in @backstage/connections, providing a human-readable display name for each configured authentication option.
Synced zod-validation-error versions between packages. Contributed by @deejay1 in #34224.

Security Fixes

This release does not contain any security fixes.

Contributors

Big shoutout to all 25 of you amazing folks who chipped in on this release: @ATKasem, @AlexandruCatalinPitaLSEG, @Dasmat13, @Elhefes, @UsainBloot, @apc-kamezaki, @clairep94, @deejay1, @djamaile, @dyatko, @jabrks, @jonkoops, @jroebu14, @karthikjeeyar, @lexhuismans-wk, @mitsukado-shinagawa, @mtlewis, @neoreddog, @officialasishkumar, @rishim-personal, @samarthsinh2660, @sikehish, @sspadotto, @vanessaliu, @zcmander

Upgrade path

We recommend that you keep your Backstage project up to date with this latest release. For more guidance on how to upgrade, check out the documentation for keeping Backstage updated.

Links and References

Below you can find a list of links and references to help you learn about and start using this new release.

Backstage official website, documentation, and getting started guide
GitHub repository
Backstage's versioning and support policy
Community Discord for discussions and support
Changelog
Backstage Demos, Blog, Roadmap and Plugins