docs/releases/v1.53.0-changelog.md
Upgrade Helper: https://backstage.github.io/upgrade-helper/?to=1.53.0
wrapInOpenApiTestServer. This function redirected test traffic through the Optic capture proxy via the OPTIC_PROXY environment variable. Since the Optic dependency has been removed, this function no longer serves a purpose. Use wrapServer instead for OpenAPI spec validation in tests.bootstrapEnvProxyAgents export along with the global-agent and undici dependencies. 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.versions:bump command no longer bootstraps legacy proxy agents. 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.BACKSTAGE_ENV environment variable, 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.title field to connection auth methods, providing a human-readable display name for each configured authentication option. Connection type authors must now provide a title for each auth method definition, while connection configuration may optionally override the title per auth entry. When not explicitly configured, the auth entry title defaults to the auth method title defined by the connection type.NODE_USE_ENV_PROXY=1 alongside your HTTP_PROXY/HTTPS_PROXY/NO_PROXY environment variables instead.@backstage/plugin-app-module-user-settings module.@types/node to 22.20.0 in the seed lockfile to prevent yarn from resolving the * wildcard (from @jest/environment-jsdom-abstract) to @types/[email protected], which breaks tsc:full due to incompatible EventEmitter types in tarn.84171b3: BREAKING: Replaced @useoptic/optic and @useoptic/openapi-utilities with oasdiff for OpenAPI breaking change detection.
To migrate, remove @useoptic/optic from your root package.json and install the oasdiff CLI on your system — see https://github.com/oasdiff/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 JSON and text output formats have changed to match oasdiff's native output.
The repo schema openapi diff command now automatically detects all packages with a changed src/schema/openapi.yaml and runs oasdiff against them directly. Packages no longer need a "diff" script in their package.json to be included in the check.
Removed the package schema openapi init and repo schema openapi test commands, which depended on the Optic capture workflow and have no equivalent with oasdiff. Runtime validation of your API against its OpenAPI spec is still available via wrapServer from @backstage/backend-openapi-utils/testUtils.
js-yaml from 4.1.1 to 4.2.0react-aria-components. The types Selection, SortDirection, and Key are available as type-only exports (use import type), while Focusable is a runtime export. Consumers can now import these directly from @backstage/ui instead of depending on react-aria-components, avoiding version mismatches.2341682: Make PluginHeader > Breadcrumbs separator align with rest of text
Affected components: PluginHeader
791703e: Add breadcrumbs prop & breadcrumbs to PluginHeader. When passed breadcrumbs, PluginHeader renders a nav with breadcrumbs & visually hides the plugin title.
These breadcrumbs:
Affected components: PluginHeader
066c7ac: Added a new TextAreaField component for multi-line text input, following the same conventions as TextField with support for a label, secondary label, and description.
ba49e37: BREAKING ALPHA: The EntityContextMenuItemBlueprint now outputs menu item data instead of a rendered MUI element. The Catalog entity page consumes this data and renders BUI menu items.
The source-level icon, useProps, and filter authoring model remains, with icon now typed as IconElement. We recommend using Remix icons and checking that custom icons follow the standard icon sizing requirements.
Menu items close immediately when selected, including while asynchronous actions are pending.
15719cc: Added an alpha BUI-ready entity header layout extension point. Its loaded component receives Catalog-composed tabs and the active tab ID, allowing custom entity headers to preserve or customize entity-page navigation.
DEPRECATED ALPHA: The existing opaque entity header extension point is deprecated. It continues to work through a temporary Catalog legacy-layout fallback so adopters can migrate custom entity headers incrementally.
EntityTypePicker's initialFilter prop was being cleared when used alongside EntityKindPicker inside EntityListProvider. The type filter is now correctly preserved after the available types load for the selected kind./api/mcp-actions/v1 or a configured named-server endpoint.auth.clientIdMetadataDocuments configuration while retaining compatibility with the deprecated experimental key.connection config option for the Redis cache store now accepts either a string URL or an object with additional connection options that are passed directly to the underlying client. The object form is only supported when backend.cache.store is redis; other stores require a plain string. This allows configuring options like pingInterval without needing dedicated config fields. For clustered Redis, the connection object properties are merged into cluster defaults. Fixes https://github.com/backstage/backstage/issues/31813, https://github.com/backstage/backstage/issues/31742.mysql:8 tag to mysql:8.4 and replacing a startup flag that was removed in MySQL 8.4. Connection pool reduced from 50 to 5 per test database, idle connections are now reaped after 5 seconds, and container connection limits raised to 1000 for both MySQL and Postgres to handle parallel Jest workers on high-core machines.config.d.ts configuration schema files. These declaration files are not covered by the TypeScript compiler's unused-variable checks, which previously allowed a stray import to slip through. Such an import can resolve during local development but break configuration schema loading for consumers of the published package, so it is now caught at lint time.backend.database.connection.flags.postgres and backend.database.connection.flags.initdb configuration properties.js-yaml from 4.1.1 to 4.2.00 when no filters are configured.if predicates now support specifying an action attribute in the permission reference. When a permission name contains a # separator (e.g. catalog.entity.read#read), the part after # is used as attributes.action when evaluating the permission. This removes the need to configure action attributes separately for basic permissions.a5b2811: Adds useBreadcrumbEntries hook, BreadcrumbEntry component, and BreadcrumbsRegistryProvider for managing breadcrumb trails across the component tree for plugins using new frontend system. Completes wiring so that new frontend system plugin Pages and SubPages get automatic-population of PluginHeader breadcrumbs.
PageLayout registers a root breadcrumb for each plugin page and passes the breadcrumb trail to PluginHeaderPageBlueprint automatically wraps each sub-page route element with BreadcrumbEntry, so sub-pages contribute to the PluginHeader breadcrumb trail without extra wiring.BreadcrumbEntry manually.
plugin-scaffolder internal routes have been wrapped as an exampleUpdated dependencies
a5b2811: Adds useBreadcrumbEntries hook, BreadcrumbEntry component, and BreadcrumbsRegistryProvider for managing breadcrumb trails across the component tree for plugins using new frontend system. Completes wiring so that new frontend system plugin Pages and SubPages get automatic-population of PluginHeader breadcrumbs.
PageLayout registers a root breadcrumb for each plugin page and passes the breadcrumb trail to PluginHeaderPageBlueprint automatically wraps each sub-page route element with BreadcrumbEntry, so sub-pages contribute to the PluginHeader breadcrumb trail without extra wiring.BreadcrumbEntry manually.
plugin-scaffolder internal routes have been wrapped as an example3ef5974: Added support for wildcard plugin entries in frontend discovery endpoints, matching the backend discovery behavior.
6172725: Fixed the default fetch API to support discovery endpoints that only define an internal target.
Updated dependencies
auth.clientIdMetadataDocuments configuration. The previous auth.experimentalClientIdMetadataDocuments key remains supported as a deprecated alias. Dynamic Client Registration now logs a deprecation warning when enabled and users should migrate to CIMD./v1/revoke endpoint is now available whenever dynamic client registration or client ID metadata documents are enabled, and is advertised through revocation_endpoint in the OpenID provider configuration.prompt setting for Auth0 authorization requests. Set it to
auto to let Auth0 determine whether the user needs to be prompted. Existing
configurations continue to use consent by default.screen_hint and login_hint parameter forwarding for the Auth0 authentication provider.
When these parameters are present in the OAuth start request query string, they
are forwarded to Auth0's /authorize endpoint. This allows callers to guide
users to the signup or login screen (screen_hint=signup) and pre-fill the
email field ([email protected]) during invitation flows.ba49e37: Migrated the new frontend system Catalog entity context menu to BUI and switched its built-in action icons to Remix icons. The old frontend system Catalog context menu remains unchanged.
BREAKING ALPHA: The new frontend system Catalog entity page now consumes data-driven context menu item extensions. Its contextMenuItems input expects the EntityContextMenuItemBlueprint data output rather than a rendered React element.
The default English value of the entityContextMenu.moreButtonAriaLabel translation changed from more to More actions. If you provide localized Catalog messages, update this label as appropriate for your locale.
15719cc: BREAKING ALPHA: Migrated the new frontend system Catalog entity page to the automatic Catalog plugin header and 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 with the previous MUI tabs and page shell. Migrate those customizations to the new BUI-ready entity header layout extension point to receive composed tabs and the active tab ID. The new extension point wins when both customization types match an entity.
The default BUI navigation does not render entity-content tab icons because the BUI Header tab API does not expose an icon slot. Legacy fallback pages retain their existing tab-icon behavior.
Added the translation keys entityLabels.systemLabel, entityLabels.domainLabel, and entityLabels.partOfLabel. Apps that provide Catalog translations should add translations for these new messages.
a00547f: Fix crash when exporting the catalog with unset filters.
1217673: Fixed a crash in the catalog export when an entity list filter is undefined, which could occur if optional filters were not set.
Updated dependencies
userGroupMember.path together with user.filter is now rejected with a configuration error, as the two options are mutually exclusive. This matches the existing validation for userGroupMember.filter and userGroupMember.search.events.modules.azureDevOps.webhookSecret is configured; without it, no route is exposed. Incoming requests are validated against the x-ado-webhook-secret custom header using timing-safe comparison.js-yaml from 4.1.1 to 4.2.0a5b2811: Adds useBreadcrumbEntries hook, BreadcrumbEntry component, and BreadcrumbsRegistryProvider for managing breadcrumb trails across the component tree for plugins using new frontend system. Completes wiring so that new frontend system plugin Pages and SubPages get automatic-population of PluginHeader breadcrumbs.
PageLayout registers a root breadcrumb for each plugin page and passes the breadcrumb trail to PluginHeaderPageBlueprint automatically wraps each sub-page route element with BreadcrumbEntry, so sub-pages contribute to the PluginHeader breadcrumb trail without extra wiring.BreadcrumbEntry manually.
plugin-scaffolder internal routes have been wrapped as an examplec32e636: Fixed an issue where Bitbucket Cloud and Bitbucket Server hosts would not render the correct repository and branch picker fields in the Scaffolder.
Updated dependencies
DatabaseTaskStore.list returning totalTasks as a string on PostgreSQL. knex returns a COUNT(*) aggregate as a string on PostgreSQL (the column is a bigint) while better-sqlite3 returns a number, so the count is now coerced with Number(...) and guarded with Number.isSafeInteger(...). This in turn fixes the list-scaffolder-tasks action, whose output schema declares totalTasks: z.number() and previously failed validation in production with Invalid output ... totalTasks: Expected number, received string.dompurify from 3.4.5 to 3.4.9dompurify from 3.4.9 to 3.4.11js-yaml from 4.1.1 to 4.2.0