RATATOSK
← All releases

Backstagev1.57.0

Security 7Breaking changes 46Deprecations 5Important fixes 25Enhancements 28Other changes 34

Get Backstage alerts

Email is sent weekly only when there are changes to check; critical security advisories are sent immediately.

Check before upgrading

Prerequisites4
Deprecated front-end APIs removed

The release also adds further deprecations and calls out custom extensions and API implementations for updates during the upgrade.

This release removes several deprecated APIs from the front-end system and introduces further deprecations. Update custom extensions and API implementations when upgrading:
github.com/backstage/backstage/releases/tag/v1.57.0
Node.js 26 compatibility warnings for avsc and node-gyp

avsc versions before 5.7.8 can break tests, and node-gyp 12.3.0 cannot download headers through a proxy. The note specifies yarn up -R avsc or yarn up -R node-gyp for lockfiles containing the affected versions.

The supported Node.js versions are now 24 and 26. Update `engines.node` in your root `package.json` to `^24.15.0 || ^26.13.0`, and check the versions used in your CI workflows and Docker images. Versions of `avsc` before 5.7.8 can break tests on Node.js 26, and `node-gyp` 12.3.0 cannot download headers through a proxy on that version; run `yarn up -R avsc` or `yarn up -R node-gyp` if your lockfile contains the affected versions.
github.com/backstage/backstage/releases/tag/v1.57.0
ES2024 frontend APIs require newer browser versions

Because Backstage provides no polyfills, users' browsers need Chrome or Edge 119, Firefox 121, or Safari 17.4 or later to run this code.

The CLI now compiles for ES2024 and requires TypeScript 5.9 or later. Backstage does not include polyfills, so frontend code using ES2024 APIs such as `Object.groupBy` needs Chrome or Edge 119, Firefox 121, or Safari 17.4 or later. Contributed by [@sebdanielsson](https://github.com/sebdanielsson) in [#36512](https://github.com/backstage/backstage/pull/36512) and [#36509](https://github.com/backstage/backstage/pull/36509).
github.com/backstage/backstage/releases/tag/v1.57.0
Instructions for preparing the PostgreSQL column and index before deployment
2 items from linked documents
  • Backend package dependency restoration instructions
  • Catalog change-feed API and deletion tracking unavailableOn SQLite and MySQL, writes from older instances during a rolling upgrade can overwrite content while retaining an assigned generation, so a non-null generation does not prove complete change tracking. PostgreSQL triggers track generation assignments for older-instance writes; any future feed would need an explicit rollout activation boundary and initial synchronization strategy.
Original release notes
The catalog database upgrade also adds publication bookkeeping and builds an index concurrently on PostgreSQL. The index build scans the catalog table and can exceed deployment startup deadlines on large installations. Review [upgrading large installations](https://github.com/backstage/backstage/blob/master/plugins/catalog-backend/README.md#upgrading-large-installations) for instructions on preparing the column and index before deploying.
github.com/backstage/backstage/releases/tag/v1.57.0
Upgrade guide2
App, plugin, and frontend migration guides
1 more lines from the upgrade guide
  • Routing migration notes and page router setup guide
Original release notes
If you are migrating an app, start with the [app migration guide](../frontend-system/building-apps/08-migrating.md). Plugin authors can follow the [plugin migration guide](../frontend-system/building-plugins/05-migrating.md). Apps and plugins already using the front-end system should review the breaking changes below and the [1.57 frontend migration notes](../frontend-system/architecture/60-migrations.md#157).
github.com/backstage/backstage/releases/tag/v1.57.0
Keeping Backstage up to date
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](https://backstage.io/docs/getting-started/keeping-backstage-updated).
github.com/backstage/backstage/releases/tag/v1.57.0

Security7Security status unclear1

Links using javascript:, data:, or vbscript: made inert

AffectsApps with links using javascript:, data:, or vbscript:
Show release-note lines
Backstage UI routing is configured automatically in Backstage apps. Standalone apps must provide a `useNavigation` hook to `BUIProvider` if they previously relied on automatic React Router integration. `routerOptions` now only accepts `replace` and `state`, and links using `javascript:`, `data:`, or `vbscript:` become inert. See the [routing migration notes](../frontend-system/architecture/60-migrations.md#157) and [page router guide](../frontend-system/building-plugins/10-page-routers.md) for setup and migration examples.
github.com/backstage/backstage/releases/tag/v1.57.0

Backstage CLI refresh token revocation fixed

Affectssetups using the Backstage CLI auth logout command
Show release-note lines
Sign-in resolvers now issue canonical, deduplicated entity references in user token claims, and `auth logout` correctly revokes the CLI refresh token. A service-authenticated `POST /v1/offline-sessions/revoke` endpoint lets backends revoke all of a user's offline sessions when `auth.experimentalRefreshToken.enabled` is set. Cursor clients are allowed to use CIMD by default, contributed by [@pjohannis](https://github.com/pjohannis) in [#36568](https://github.com/backstage/backstage/pull/36568).
github.com/backstage/backstage/releases/tag/v1.57.0

Backstage UI routing configuration updated

AffectsBackstage apps and standalone apps using automatic React Router integration

Backstage apps now receive Backstage UI routing configuration automatically. Standalone apps that relied on automatic React Router integration must provide a useNavigation hook to BUIProvider.

Show release-note lines
Backstage UI routing is configured automatically in Backstage apps. Standalone apps must provide a `useNavigation` hook to `BUIProvider` if they previously relied on automatic React Router integration. `routerOptions` now only accepts `replace` and `state`, and links using `javascript:`, `data:`, or `vbscript:` become inert. See the [routing migration notes](../frontend-system/architecture/60-migrations.md#157) and [page router guide](../frontend-system/building-plugins/10-page-routers.md) for setup and migration examples.
github.com/backstage/backstage/releases/tag/v1.57.0

Auth backend OAuth service now requires S256 PKCE

Security status unclear
Affectsclients of the auth backend's OAuth service

The service previously accepted and advertised plain; clients using it are now rejected and need to generate SHA-256 challenges. Existing CIMD clients and pre-registered clients with a secret must also use S256.

Show release-note lines
All clients of the auth backend's OAuth service, including existing CIMD clients and pre-registered clients with a secret, now require Proof Key for Code Exchange (PKCE) with the `S256` challenge method. The `plain` method is no longer accepted or advertised. Update clients that use `plain` to generate SHA-256 challenges. Pre-registered client support and PKCE changes contributed by [@drodil](https://github.com/drodil) in [#36567](https://github.com/backstage/backstage/pull/36567).
github.com/backstage/backstage/releases/tag/v1.57.0

GitHub, GitLab, and Azure DevOps webhook endpoints reject requests without secrets

AffectsSetups using the GitHub, GitLab, or Azure DevOps events modules' own webhook endpoints
Additional actionWebhook secrets configured under the relevant module settings: events.modules.github, events.modules.gitlab, or events.modules.azureDevOps; GitHub App secrets are also supported.

Requests without a configured secret receive HTTP 403. GitHub can also use a secret configured per GitHub App; routes configured only through events.http.topics remain without a validator.

Show release-note lines
The GitHub, GitLab, and Azure DevOps events modules now reject requests to their webhook endpoints with HTTP 403 when no webhook secret is configured. Configure secrets under `events.modules.github`, `events.modules.gitlab`, and `events.modules.azureDevOps` before upgrading; GitHub also supports secrets configured per GitHub App. This applies to the modules' own endpoints; routes configured only through `events.http.topics` still have no validator attached.
github.com/backstage/backstage/releases/tag/v1.57.0

TechDocs S3 connection leak fixed

AffectsTechDocs served from S3

When a browser navigated away before a file finished loading, the response stream kept its pooled connection; after 50 such disconnects, requests failed with a socket timeout. Early response closes now destroy the S3 stream, preventing this pool exhaustion.

Show release-note lines
- TechDocs releases storage connections when browsers disconnect early, including a fix for S3 connection pool exhaustion. Contributed in part by [@lvthillo](https://github.com/lvthillo) in [#36468](https://github.com/backstage/backstage/pull/36468).
github.com/backstage/backstage/releases/tag/v1.57.0

Security fixes for Backstage packages

Affectssetups using one or more of @backstage/backend-defaults, @backstage/plugin-auth-backend, @backstage/plugin-catalog-backend, @backstage/plugin-catalog-backend-module-gitlab, @backstage/plugin-events-backend-module-azure, @backstage/plugin-events-backend-module-github, @backstage/plugin-events-backend-module-gitlab, @backstage/plugin-scaffolder-backend, @backstage/plugin-scaffolder-react, @backstage/plugin-techdocs-backend, @backstage/plugin-techdocs-backend-module-zensical, @backstage/plugin-techdocs-node, or @techdocs/cli
Show release-note lines
The following packages have received security fixes:
- `@backstage/backend-defaults`
- `@backstage/plugin-auth-backend`
- `@backstage/plugin-catalog-backend`
- `@backstage/plugin-catalog-backend-module-gitlab`
- `@backstage/plugin-events-backend-module-azure`
- `@backstage/plugin-events-backend-module-github`
- `@backstage/plugin-events-backend-module-gitlab`
- `@backstage/plugin-scaffolder-backend`
- `@backstage/plugin-scaffolder-react`
- `@backstage/plugin-techdocs-backend`
- `@backstage/plugin-techdocs-backend-module-zensical`
- `@backstage/plugin-techdocs-node`
- `@techdocs/cli`
github.com/backstage/backstage/releases/tag/v1.57.0

Breaking changes46No downgrade1

Experimental DCR removed from the auth backend

No downgrade
Affectsauth backend setups using experimental DCR, including those with auth.experimentalDynamicClientRegistration configured or DCR clients and sessions in the database
Action requiredCIMD or clients pre-registered through auth.staticClients, with auth.experimentalDynamicClientRegistration removed
No downgrade(Inferred: The migration deletes DCR clients and sessions, and restoring them would require recovering that deleted state.)

The migration deletes DCR clients and their authorization and offline sessions, invalidating their authorization codes and refresh tokens. Users must sign in again, though already-issued user tokens remain valid until they expire.

Show release-note lines
The deprecated experimental Dynamic Client Registration (DCR) support has been removed from the auth backend. Use Client ID Metadata Documents (CIMD), or pre-register clients through `auth.staticClients`, and remove `auth.experimentalDynamicClientRegistration` from your configuration. The database migration deletes DCR clients and their authorization and offline sessions, invalidating their authorization codes and refresh tokens. Users must sign in again through a CIMD or pre-registered client; already-issued user tokens remain valid until they expire. See the [DCR migration guide](../ai/mcp-actions.md#migrating-from-dynamic-client-registration).
github.com/backstage/backstage/releases/tag/v1.57.0

useRouteRefParams returns only declared route parameters

Affectscode using useRouteRefParams

Previously, the hook could return an undeclared splat parameter. Code that relied on it now receives only parameters declared by the route ref.

Show release-note lines
`RouterBlueprint`, the `app/root` router input, and `convertLegacyAppOptions({ components: { Router } })` are no longer supported. Remove overrides that only install a `BrowserRouter`, move global providers to `AppRootWrapperBlueprint`, and render page adapters inside lazily loaded page components. Framework navigation destinations must start with `/` and exclude the deployment basename; use a page adapter for path-relative navigation. `useRouteRefParams` now returns only the parameters declared by its route ref, without an undeclared splat parameter. Apps using the old front-end system keep their existing routing setup.
github.com/backstage/backstage/releases/tag/v1.57.0

Extension attachment type replacement

Affectscode using ExtensionAttachTo(Inferred)

Consumers now use Extension<unknown>['attachTo'].

Show release-note lines
- Replace `ExtensionAttachTo` with `Extension<unknown>['attachTo']`, and `ProgressProps` with its existing shape, `{}`.
github.com/backstage/backstage/releases/tag/v1.57.0

Frontend useApi now unwraps promise-valued Utility API refs

Affectspromise-valued Utility API refs used with useApi from @backstage/frontend-plugin-api
Action requiredWhen changing an existing API ref to a promise, update its consumers and custom factories together.

Previously, this hook returned the promise directly; it now unwraps the API, suspending while it loads and sending rejection reasons to an error boundary. Consumers that need the promise must use useApiHolder().get(ref).

Show release-note lines
### **BREAKING**: Lazy Utility API implementations
Utility API factories can now load implementations on demand through dynamic imports. Declare the API value as a promise, for example `ApiRef<Promise<WorkApi>>`. The `useApi` hook from `@backstage/frontend-plugin-api` unwraps the promise, suspends while it is pending, and throws rejection reasons to an error boundary:
```ts
const workApiRef = createApiRef<Promise<WorkApi>>().with({
  id: 'plugin.example.work',
});
const workApi = useApi(workApiRef); // WorkApi
```
The hook's return type is now `Awaited<T>`. Consumers that intentionally used a promise returned by `useApi` must switch to `useApiHolder().get(ref)`. Changing an existing API ref to a promise changes its public contract, so update its consumers and custom factories together. Holders and factory dependencies continue to receive the declared API value unchanged. The legacy `useApi` hook from `@backstage/core-plugin-api` continues returning promises directly.
github.com/backstage/backstage/releases/tag/v1.57.0

Synchronous mocks for promise-valued APIs accepted

Affectstests using TestApiProvider, other mock API overrides, or renderInTestApp with promise-valued APIs or mocks

Previously, synchronous mocks for promise-valued APIs were not accepted; tests can now keep synchronous assertions when rendering is otherwise synchronous. While promise-valued mocks resolve, renderInTestApp supplies an empty Suspense fallback, so tests that relied on an ancestor boundary's loading UI may need updated assertions.

Show release-note lines
Page extension boundaries provide Suspense and error handling; consumers outside those boundaries must provide their own. `TestApiProvider` and other mock API overrides accept synchronous mocks even for promise-valued APIs, so tests can keep synchronous assertions when rendering is otherwise synchronous. Promise-valued mocks are also supported, with `renderInTestApp` supplying an empty Suspense fallback while they resolve. Tests that relied on an ancestor boundary's loading UI may need updated assertions. See the [Utility API documentation](../frontend-system/utility-apis/02-creating.md) for lazy factories and migration guidance.
github.com/backstage/backstage/releases/tag/v1.57.0

Test app helpers now throw on reported creation errors

AffectsTests using renderInTestApp, renderTestApp, or createExtensionTester
Action requiredInvalid test setups need to be fixed, or intentional errors allowed through isExpectedError; API overrides need to use the test app's apis option rather than a conflicting factory in extensions.

renderInTestApp and renderTestApp could previously let a test pass for a broken app. Now errors reported during app or extension-tree creation fail the test, including errors a real app only logs as warnings, unless isExpectedError accepts them.

Show release-note lines
`renderInTestApp`, `renderTestApp`, and `createExtensionTester` now throw for all errors reported while creating the test app or extension tree, including errors that a real app only logs as warnings. Fix invalid test setups, or allow an intentional error through the `isExpectedError` option. API overrides belong in the test app's `apis` option; a conflicting factory supplied through `extensions` is rejected. Contributed by [@dyatko](https://github.com/dyatko) in [#36333](https://github.com/backstage/backstage/pull/36333).
github.com/backstage/backstage/releases/tag/v1.57.0

Test apps now use per-app in-memory storage

Affectstest apps that depend on browser storage, visible notifications, global error handling, or alert replay for late subscribers
Action requiredAn explicit API implementation for tests that depend on browser storage, visible notifications, or global error handling

Toasts and errors are collected without display, and alerts are no longer replayed to late subscribers; previously, late subscribers received replayed alerts.

Show release-note lines
Test apps also use defaults designed for isolation: storage is kept in memory per app, toasts and errors are collected without displaying them, and alerts are no longer replayed to late subscribers. Tests that depend on browser storage, visible notifications, or global error handling need an explicit API implementation. Expanded `mockApis` helpers provide typed mocks and functional fakes for core APIs. Removed standalone mock types can be replaced with types derived from these helpers, such as `ReturnType<typeof mockApis.analytics>`.
github.com/backstage/backstage/releases/tag/v1.57.0

Production JSON logs gain per-line timestamps

Affectssetups using production JSON logs
Action requiredLog pipelines and dashboards that consume the request-log date field or date prefix need to use timestamp; custom JSON logger formats need format.combine(format.timestamp(), format.json()) to preserve it.

Previously, only root HTTP router request logs had a date field, repeated at the start of message; other production JSON log lines had no timestamp. Standard logs now omit those request-log values, while custom logger formats do not retain the timestamp unless they include the required format combination.

Show release-note lines
Production JSON logs now include a `timestamp` field on every line. Root HTTP router request logs no longer include a `date` field or repeat the date at the start of the message. Update log pipelines and dashboards that read either of those values to use `timestamp`. Custom JSON logger formats should combine `format.timestamp()` with `format.json()` to preserve the field.
github.com/backstage/backstage/releases/tag/v1.57.0

LDAP organization ingestion now requests mapped attributes by default

AffectsLDAP organization entity provider and LdapOrgReaderProcessor configurations
Action requiredCustom transformers needing attributes beyond the mappings must have them listed in users.options.attributes or groups.options.attributes, or request all attributes with ['*', '+']. Explicitly configured lists must include every attribute needed by mappings, vendor configuration, and transformers.

Previously, searches included all LDAP attributes, so custom transformers could read attributes beyond the mappings. After upgrading, those additional attributes may be missing from LDAP entries.

Evidence“**BREAKING**: Searches no longer request `['*', '+']` by default. This applies to both the org entity provider and `LdapOrgReaderProcessor`. When options.attributes is not explicitly configured, attributes required by map (including custom map.\* overrides and membership mappings) are requested automatically. When options.attributes is explicitly configured, the provided list is used as-is and must include all attributes required by mappings, vendor configuration, and custom transformers. Custom transformers that access other attributes from LDAP entries may now find those attributes missing.” backstage/backstage/pull/35319 ↗
Show release-note lines
LDAP organization ingestion now requests only the attributes used by configured mappings, instead of `['*', '+']`. This affects both the entity provider and `LdapOrgReaderProcessor`. Custom transformers that read additional attributes must list them in `users.options.attributes` or `groups.options.attributes`, or explicitly use `['*', '+']` to request all attributes. An explicitly configured list is used as-is and must include every attribute needed by mappings, vendor configuration, and transformers.
github.com/backstage/backstage/releases/tag/v1.57.0

LDAP entity provider defaults to parallel reads

AffectsLDAP entity providers connected to directories with connection limits that require sequential reads
Action requiredSet disableParallelReads: true on the provider for directories whose connection limits require sequential reads.

Previously, each refresh read users and groups sequentially over one LDAP connection. Now it opens two connections and binds per refresh unless disableParallelReads: true is set.

Evidence“The LDAP org entity provider now reads users and groups in parallel by default. Set `disableParallelReads: true` to use one connection and read sequentially. Parallel reads open two binds and two connections per refresh. Directories with per-client connection limits may notice the extra load after upgrading.” backstage/backstage/pull/35319 ↗
Show release-note lines
The entity provider also reads users and groups in parallel by default, opening two connections and binds per refresh. Set `disableParallelReads: true` on the provider to retain sequential reads when directory connection limits require it. Connections are closed after each refresh.
github.com/backstage/backstage/releases/tag/v1.57.0

TranslationRef values become callable functions

Affectscode that consumes TranslationRef values
Action requiredConsumers must treat TranslationRef values as opaque; they must not clone them or check them for plain-object shape.
Show release-note lines
`TranslationRef` values are now callable functions and must be treated as opaque values rather than cloned or checked for plain-object shape. Custom `TranslationApi` implementations must provide `t` in every translation snapshot, including while `ready` is false, using available messages and language fallbacks. Titles wait for the initial selected language and retain resolved values during later loads or failures, preserving page state. See the [internationalization guide](../frontend-system/building-plugins/07-internationalization.md).
github.com/backstage/backstage/releases/tag/v1.57.0

Bitbucket Cloud workspace code search now requires user-identifying credentials

AffectsBitbucket Cloud entity provider integrations using workspace code search
Action requiredWorkspace code search requires a user-identifying credential, such as an Atlassian account email as username and an API token, with both read:repository:bitbucket and read:workspace:bitbucket scopes.

Previously, the code search API did not require read:workspace:bitbucket; rejected credentials now send discovery to the source API instead of workspace code search. Adding read:workspace:bitbucket to an API token restores workspace code search.

Evidence“Bitbucket Cloud rejects app passwords, legacy OAuth consumers, and API keys for this API. An API token without `read:workspace:bitbucket` is also rejected with `403`. When that happens, or when code search is not enabled, the provider checks catalog files with the source API instead.” backstage/backstage/pull/36845 ↗
Show release-note lines
The Bitbucket Cloud entity provider now uses the workspace code search API following retirement of the previous endpoint on November 15, 2026. Workspace code search requires a credential that identifies a user, such as an Atlassian account email as `username` with an API `token`, and both `read:repository:bitbucket` and `read:workspace:bitbucket` scopes. App passwords, legacy OAuth consumers, API keys, and API tokens missing the workspace scope are rejected by that API.
github.com/backstage/backstage/releases/tag/v1.57.0

Malformed Catalog filters now return HTTP 400

AffectsCatalog query filters using $all, $any, or $not

When a filter object combines one of these operators with other keys, or gives $all or $any a non-array operand, extra keys were silently ignored and count and list queries could interpret the object differently.

Show release-note lines
Malformed predicates that combine `$all`, `$any`, or `$not` with other keys in the same object, or pass non-array operands to `$all` or `$any`, now receive a 400 response instead of silently ignoring parts of the filter. Entity lookups through `entities/by-refs` now match case-insensitively, consistent with the entity reference contract. Contributed by [@chicobento](https://github.com/chicobento) in [#36744](https://github.com/backstage/backstage/pull/36744).
github.com/backstage/backstage/releases/tag/v1.57.0

Catalog database gains publication bookkeeping

Affectscatalog backend installations using SQLite, MySQL, or PostgreSQL

On SQLite and MySQL, older instances could overwrite content while retaining a previously assigned generation, so that value did not prove complete change tracking. The upgrade adds a nullable generation column without rewriting existing entities and builds the index concurrently on PostgreSQL.

Show release-note lines
The catalog database upgrade also adds publication bookkeeping and builds an index concurrently on PostgreSQL. The index build scans the catalog table and can exceed deployment startup deadlines on large installations. Review [upgrading large installations](https://github.com/backstage/backstage/blob/master/plugins/catalog-backend/README.md#upgrading-large-installations) for instructions on preparing the column and index before deploying.
Internal publication bookkeeping adds a nullable generation column without
rewriting existing entities. PostgreSQL builds its index concurrently, but still
scans the entire catalog table, even when every generation is null.
The metadata transaction has a five-second lock-wait timeout. If it expires,
startup fails and must retry; repeated failures can cause deployment restart
loops. The concurrent index phase has no imposed timeout and can wait on long
transactions elsewhere in the database, including other plugins using separate
schemas. It may exceed deployment startup deadlines.
github.com/backstage/backstage/releases/tag/v1.57.0

Canonical, deduplicated entity references in sign-in resolver user token claims

Affectssetups using sign-in resolvers that issue user token claims containing entity references
Show release-note lines
Sign-in resolvers now issue canonical, deduplicated entity references in user token claims, and `auth logout` correctly revokes the CLI refresh token. A service-authenticated `POST /v1/offline-sessions/revoke` endpoint lets backends revoke all of a user's offline sessions when `auth.experimentalRefreshToken.enabled` is set. Cursor clients are allowed to use CIMD by default, contributed by [@pjohannis](https://github.com/pjohannis) in [#36568](https://github.com/backstage/backstage/pull/36568).
github.com/backstage/backstage/releases/tag/v1.57.0

MarkdownContent renderer loads on first use

Affectsapps that use MarkdownContent

Loading the renderer on first use reduces the app startup bundle. Tests that immediately assert on rendered Markdown may need asynchronous queries.

Show release-note lines
- `MarkdownContent` loads its renderer on first use, reducing the app startup bundle. Tests that immediately assert on rendered Markdown may need asynchronous queries.
github.com/backstage/backstage/releases/tag/v1.57.0

Backstage CLI commands preserve their exit codes

Affectsautomation that relies on Backstage CLI exit codes(Inferred)
Show release-note lines
- CLI commands preserve their exit codes, and package startup supports repeated `--import` and `--require` flags. Flag support contributed by [@dotboris](https://github.com/dotboris) in [#36647](https://github.com/backstage/backstage/pull/36647).
github.com/backstage/backstage/releases/tag/v1.57.0

Legacy app router APIs no longer supported

Affectsapps using RouterBlueprint, the app/root router input, convertLegacyAppOptions({ components: { Router } }), or overrides that install a BrowserRouter
Action requiredRemove overrides that only install a BrowserRouter, move global providers to AppRootWrapperBlueprint, and render page adapters inside lazily loaded page components.
Show release-note lines
`RouterBlueprint`, the `app/root` router input, and `convertLegacyAppOptions({ components: { Router } })` are no longer supported. Remove overrides that only install a `BrowserRouter`, move global providers to `AppRootWrapperBlueprint`, and render page adapters inside lazily loaded page components. Framework navigation destinations must start with `/` and exclude the deployment basename; use a page adapter for path-relative navigation. `useRouteRefParams` now returns only the parameters declared by its route ref, without an undeclared splat parameter. Apps using the old front-end system keep their existing routing setup.
github.com/backstage/backstage/releases/tag/v1.57.0

routerOptions now accepts only replace and state

Affectscode configuring routerOptions with values other than replace or state
Show release-note lines
Backstage UI routing is configured automatically in Backstage apps. Standalone apps must provide a `useNavigation` hook to `BUIProvider` if they previously relied on automatic React Router integration. `routerOptions` now only accepts `replace` and `state`, and links using `javascript:`, `data:`, or `vbscript:` become inert. See the [routing migration notes](../frontend-system/architecture/60-migrations.md#157) and [page router guide](../frontend-system/building-plugins/10-page-routers.md) for setup and migration examples.
github.com/backstage/backstage/releases/tag/v1.57.0

DialogApi.open replaces show and showModal

AffectsExtensions and API implementations using the dialog API(Inferred)
Action requiredUpdate custom extensions and API implementations that use show or showModal; use DialogApi.open with your own dialog presentation and the core.dialog.v2 API reference, and upgrade @backstage/plugin-app alongside @backstage/frontend-plugin-api.
Show release-note lines
- Use `DialogApi.open` with your own dialog presentation instead of `show` or `showModal`, and `IconsApi.icon` instead of `getIcon`. Upgrade `@backstage/plugin-app` alongside `@backstage/frontend-plugin-api`; the API references are now `core.dialog.v2` and `core.icons.v2`.
github.com/backstage/backstage/releases/tag/v1.57.0

Icon API now uses IconsApi.icon and core.icons.v2

Affectsextensions and API implementations using the icon API(Inferred)
Action requiredUpgrade @backstage/plugin-app alongside @backstage/frontend-plugin-api.
Show release-note lines
- Use `DialogApi.open` with your own dialog presentation instead of `show` or `showModal`, and `IconsApi.icon` instead of `getIcon`. Upgrade `@backstage/plugin-app` alongside `@backstage/frontend-plugin-api`; the API references are now `core.dialog.v2` and `core.icons.v2`.
github.com/backstage/backstage/releases/tag/v1.57.0

Removal of the @backstage/frontend-plugin-api/alpha entry point

Affectsimports from @backstage/frontend-plugin-api/alpha(Inferred)
Action requiredReplace imports from @backstage/frontend-plugin-api/alpha with imports from the main entry point.

The exports retain the same behavior and identity at the main entry point.

Show release-note lines
- Replace imports from `@backstage/frontend-plugin-api/alpha` with imports from the main entry point. The `/alpha` entry point has been removed; its exports retain the same behavior and identity at their new location.
github.com/backstage/backstage/releases/tag/v1.57.0

IconBundleBlueprint now requires icon elements

Affectsextensions using IconBundleBlueprint, IconComponent, or Material UI icons in icon bundles
Action requiredUse IconElement instead of IconComponent and supply icon elements to IconBundleBlueprint; for Material UI icons, use <MyIcon fontSize="inherit" />.

Previously, IconBundleBlueprint took icon components, and the IconComponent type was available. Icons passed through convertLegacyAppOptions are still converted automatically, and auth provider icons still accept components.

Show release-note lines
- Use `IconElement` instead of the removed `IconComponent` type. `IconBundleBlueprint` now requires elements such as `icons: { user: <MyIcon /> }` rather than components. For Material UI icons, use `<MyIcon fontSize="inherit" />`. Icons passed through `convertLegacyAppOptions` are converted automatically, and auth provider icons continue to accept components.
github.com/backstage/backstage/releases/tag/v1.57.0

Specialized app setup moved to the prepare/finalize flow

Affectsapps using createSpecializedApp
Action requiredReplace createSpecializedApp with prepareSpecializedApp(options).finalize(). Apps with sign-in or asynchronous session preparation must render the bootstrap app and subscribe through onFinalized(); advanced.sessionState can be used to reuse a finalized session.
Show release-note lines
- Use `prepareSpecializedApp(options).finalize()` instead of `createSpecializedApp`. Apps with sign-in or asynchronous session preparation must render the bootstrap app and subscribe through `onFinalized()`. Use `advanced.sessionState` to reuse a finalized session, and `ApiBlueprint` extensions to register custom APIs.
github.com/backstage/backstage/releases/tag/v1.57.0

Custom APIs registered with ApiBlueprint extensions

Affectsextensions that register custom APIs
Show release-note lines
- Use `prepareSpecializedApp(options).finalize()` instead of `createSpecializedApp`. Apps with sign-in or asynchronous session preparation must render the bootstrap app and subscribe through `onFinalized()`. Use `advanced.sessionState` to reuse a finalized session, and `ApiBlueprint` extensions to register custom APIs.
github.com/backstage/backstage/releases/tag/v1.57.0

Custom navigation components now use navItems

Affectscustom navigation components

They previously received a flat items collection; they now access items through navItems.rest(), using item.href and item.title, and render item.icon as a React element.

Show release-note lines
- Custom navigation components now receive `navItems` instead of the flat `items` collection. Use `navItems.rest()`, `item.href`, and `item.title`, and render `item.icon` as a React element.
github.com/backstage/backstage/releases/tag/v1.57.0

Analytics and extension middleware import locations changed

Affectsprojects importing the named analytics exports or ExtensionFactoryMiddleware(Inferred)

AnalyticsImplementation, AnalyticsImplementationBlueprint, and AnalyticsImplementationFactory are imported from @backstage/plugin-app-react; ExtensionFactoryMiddleware is imported from @backstage/frontend-app-api.

Show release-note lines
- Import `AnalyticsImplementation`, `AnalyticsImplementationBlueprint`, and `AnalyticsImplementationFactory` from `@backstage/plugin-app-react`, and `ExtensionFactoryMiddleware` from `@backstage/frontend-app-api`.
github.com/backstage/backstage/releases/tag/v1.57.0

withApis replaced by function components using useApi

Affectsfrontend-system code using withApis(Inferred)
Action requiredReplace withApis with a function component using useApi.
Show release-note lines
- Replace `withApis` with a function component using `useApi`. Use `FrontendPlugin.pluginId`, `PageLayoutTab`, and `CreateFrontendPluginOptions` instead of the removed `id`, `PageTab`, and `PluginOptions` aliases.
github.com/backstage/backstage/releases/tag/v1.57.0

Frontend plugin aliases removed

AffectsExtensions using the id, PageTab, or PluginOptions aliases(Inferred)
Action requiredUse FrontendPlugin.pluginId, PageLayoutTab, and CreateFrontendPluginOptions instead of the removed id, PageTab, and PluginOptions aliases.

Before this release, extensions used those aliases in place of the named replacements. After upgrading, the named replacement property and types are used.

Show release-note lines
- Replace `withApis` with a function component using `useApi`. Use `FrontendPlugin.pluginId`, `PageLayoutTab`, and `CreateFrontendPluginOptions` instead of the removed `id`, `PageTab`, and `PluginOptions` aliases.
github.com/backstage/backstage/releases/tag/v1.57.0

ProgressProps replaced with its existing {} shape

Affectsconsumers using ProgressProps(Inferred)
Show release-note lines
- Replace `ExtensionAttachTo` with `Extension<unknown>['attachTo']`, and `ProgressProps` with its existing shape, `{}`.
github.com/backstage/backstage/releases/tag/v1.57.0

Ignored anchorOrigin option removed from alert and toast settings

Affectsbuilt-in alert display configurations or toast display props that specify anchorOrigin(Inferred)

These settings accepted anchorOrigin, but the option was ignored.

Show release-note lines
- Remove the ignored `anchorOrigin` option from built-in alert display configuration and toast display props.
github.com/backstage/backstage/releases/tag/v1.57.0

FrontendFeature plugins must provide pluginId

Affectsplugins passed as a FrontendFeature that predate the pluginId property
Action requiredPlugins that predate the pluginId property must be rebuilt against a current framework version
Show release-note lines
Plugins passed as a `FrontendFeature` must now provide `pluginId`. Rebuild plugins that predate this property against a current framework version.
github.com/backstage/backstage/releases/tag/v1.57.0

Standalone mock types removed

Affectstest code using standalone mock types

Standalone mock types were available before this release. Their types can now be derived from mockApis helpers, for example with ReturnType<typeof mockApis.analytics>.

Show release-note lines
Test apps also use defaults designed for isolation: storage is kept in memory per app, toasts and errors are collected without displaying them, and alerts are no longer replayed to late subscribers. Tests that depend on browser storage, visible notifications, or global error handling need an explicit API implementation. Expanded `mockApis` helpers provide typed mocks and functional fakes for core APIs. Removed standalone mock types can be replaced with types derived from these helpers, such as `ReturnType<typeof mockApis.analytics>`.
github.com/backstage/backstage/releases/tag/v1.57.0

Navigation tests now use framework routing for page matching

Affectsnavigation tests with elements that need routing-library context
Action requiredTest elements that need routing-library context must be wrapped in a page adapter.
Show release-note lines
Both render helpers now return an `apis` holder with access to the same Utility API instances used by components, including test overrides. For navigation tests, use `apis.get(coreApis.appHistory)` to access the app history. Page matching uses framework routing; wrap test elements in a page adapter when they need routing-library context. See the [navigation testing guide](../frontend-system/building-plugins/02-testing.md#navigation-and-app-history).
github.com/backstage/backstage/releases/tag/v1.57.0

Supported Node.js versions move from 22 and 24 to 24 and 26

AffectsBackstage setups using Node.js 22 or specifying Node.js versions in the root engines.node, CI workflows, or Docker images
Action requiredRoot package.json engines.node set to ^24.15.0 || ^26.13.0, with matching Node.js versions in CI workflows and Docker images; create-app requires Node.js 24.15.0+ or 26.13.0+.
Show release-note lines
The supported Node.js versions are now 24 and 26. Update `engines.node` in your root `package.json` to `^24.15.0 || ^26.13.0`, and check the versions used in your CI workflows and Docker images. Versions of `avsc` before 5.7.8 can break tests on Node.js 26, and `node-gyp` 12.3.0 cannot download headers through a proxy on that version; run `yarn up -R avsc` or `yarn up -R node-gyp` if your lockfile contains the affected versions.
github.com/backstage/backstage/releases/tag/v1.57.0

Backstage CLI compilation target raised to ES2024

AffectsBackstage CLI package builds, app bundles, and backend development transforms
Action requiredTypeScript 5.9 or later; for frontend use of ES2024 built-ins, Chrome or Edge 119, Firefox 121, or Safari 17.4 or later

These builds and transforms move from ES2023 to ES2024. Frontend code using ES2024 built-ins has no polyfills.

Show release-note lines
The CLI now compiles for ES2024 and requires TypeScript 5.9 or later. Backstage does not include polyfills, so frontend code using ES2024 APIs such as `Object.groupBy` needs Chrome or Edge 119, Firefox 121, or Safari 17.4 or later. Contributed by [@sebdanielsson](https://github.com/sebdanielsson) in [#36512](https://github.com/backstage/backstage/pull/36512) and [#36509](https://github.com/backstage/backstage/pull/36509).
github.com/backstage/backstage/releases/tag/v1.57.0

React 18 required by most frontend packages

Affectsapps using frontend packages, especially React 17 apps and the old front-end system
Action requiredReact 18

The old front-end system core packages keep React 17 in their own peer dependency ranges, but their dependencies require React 18.

Show release-note lines
Most frontend packages now require React 18. The old front-end system core packages retain React 17 in their own peer dependency ranges, but their dependencies include packages that require React 18, so apps using the old system also need to plan the upgrade. See the [React 18 migration guide](../tutorials/react18-migration.md) and [frontend migration notes](../frontend-system/architecture/60-migrations.md#react-17-support-removed).
github.com/backstage/backstage/releases/tag/v1.57.0

createGitlabTokenValidator now requires a logger argument

Affectscustom calls to createGitlabTokenValidator
Action requiredCustom callers of createGitlabTokenValidator must supply its new logger argument.
Show release-note lines
For development setups that deliberately accept unauthenticated events, each module provides an explicit `dangerouslyAllowUnauthenticatedEvents: true` option. Custom users of `createGitlabTokenValidator` must also supply its new `logger` argument. See the configuration sections for the [GitHub](https://github.com/backstage/backstage/blob/master/plugins/events-backend-module-github/README.md#configuration), [GitLab](https://github.com/backstage/backstage/blob/master/plugins/events-backend-module-gitlab/README.md#configuration), and [Azure DevOps](https://github.com/backstage/backstage/blob/master/plugins/events-backend-module-azure/README.md#configuration) modules.
github.com/backstage/backstage/releases/tag/v1.57.0

Scaffolder Google Cloud task recovery save failures fixed

Affectstask recovery configured with the Scaffolder Google Cloud module
Action requiredBefore upgrading, grant the backend's Google Cloud credentials storage.objects.list on the task recovery bucket, in addition to the existing object permissions.

When template steps finished in quick succession, snapshots could overwrite the same Google Cloud Storage object, hit its mutation rate limit, and cause task recovery workspace saves to fail. Saves now use separate objects; recovery restores the latest snapshot and supports snapshots from older versions, while older snapshots are cleaned up after successful saves and cleanup failures are logged as warnings.

Evidence“Fixed task recovery workspace saves failing with Google Cloud Storage rate limit errors when template steps finish in quick succession. Each snapshot is saved to a separate object, and recovery continues to support snapshots from older versions.” backstage/backstage/pull/36466 ↗
Show release-note lines
### **BREAKING**: Google Cloud task recovery permissions
The Scaffolder Google Cloud module now stores each task recovery snapshot as a separate object, avoiding storage rate limits when template steps finish in quick succession. Grant the backend's Google Cloud credentials `storage.objects.list` on the task recovery bucket before upgrading, in addition to the existing object permissions. Recovery continues to support snapshots saved by older versions.
github.com/backstage/backstage/releases/tag/v1.57.0

Backend HTTP router services add addWebSocketHandler for WebSocket routes

Affectssetups with custom HttpRouterService or RootHttpRouterService implementations, or using backend test utilities
Action requiredCustom implementations of HttpRouterService and RootHttpRouterService must implement addWebSocketHandler.
Show release-note lines
The backend HTTP router services now provide `addWebSocketHandler` for registering WebSocket upgrade routes. Routes require token authentication by default, and browser clients can pass bearer tokens through the WebSocket protocol header. Cookie authentication is not supported. Custom implementations of `HttpRouterService` and `RootHttpRouterService` must implement the new method; the backend test utilities support it too.
github.com/backstage/backstage/releases/tag/v1.57.0

Express-only WebSocket upgrade handling moved to router API

Affectsplugins handling WebSocket upgrades only through Express, with the framework's server-level listener active

When the framework's server-level listener is the only one, upgrades not matched through the router receive a 404. Existing server upgrade listeners can coexist during migration, and the router provides addWebSocketHandler to register upgrade routes.

Show release-note lines
The Signals backend uses this API, fixing first connections that previously required an HTTP request before the WebSocket could connect. Existing server upgrade listeners can coexist during migration, but plugins that handle upgrades only through Express, such as the Kubernetes proxy, must migrate to the router API when the framework's server-level listener is active. Otherwise, unmatched upgrades receive a 404 response when it is the only server-level listener. See the [HTTP router service documentation](../backend-system/core-services/http-router.md).
github.com/backstage/backstage/releases/tag/v1.57.0

t required in custom TranslationApi snapshots

Affectssetups with custom TranslationApi implementations
Action requiredCustom TranslationApi implementations must provide t in every translation snapshot, including while ready is false, using available messages and language fallbacks.
Show release-note lines
`TranslationRef` values are now callable functions and must be treated as opaque values rather than cloned or checked for plain-object shape. Custom `TranslationApi` implementations must provide `t` in every translation snapshot, including while `ready` is false, using available messages and language fallbacks. Titles wait for the initial selected language and retain resolved values during later loads or failures, preserving page state. See the [internationalization guide](../frontend-system/building-plugins/07-internationalization.md).
github.com/backstage/backstage/releases/tag/v1.57.0

coreServices and mockServices objects frozen

Affectsruntime mutation of coreServices or mockServices, or spying on mockServices helper objects

These operations were previously supported but are no longer supported. Existing calls and types remain available, and mocks created by the helpers are unaffected.

Show release-note lines
- `coreServices` and `mockServices` are now frozen objects. Existing calls and types remain available, but runtime mutation and spying on the mock service helpers themselves are no longer supported; the mocks they create are unaffected.
github.com/backstage/backstage/releases/tag/v1.57.0

OpenAPI generation failures now return non-zero exit codes outside watch mode

AffectsOpenAPI client or server generation via package schema openapi generate

Previously, failures such as package lint failing on generated output could still leave the command with exit code 0. Outside watch mode, it now exits non-zero after the generators settle; watch mode logs errors and continues watching.

Evidence“Outside watch mode they now wrap and rethrow the error, and `generate/index.ts` waits for all running generators to settle before exiting so a failure in one doesn't cut off the other mid-run. Watch mode still logs the error and keeps watching.” backstage/backstage/pull/36854 ↗
Show release-note lines
- OpenAPI client and server generation commands exit with a non-zero status when generation fails, allowing CI to detect failures. Watch mode keeps watching after errors. Contributed by [@aksharprabhudesai](https://github.com/aksharprabhudesai) in [#36854](https://github.com/backstage/backstage/pull/36854).
github.com/backstage/backstage/releases/tag/v1.57.0

@backstage/cli-module-package-manager-yarn makes Yarn dependencies optional peers

Affectsinstallations of @backstage/cli-module-package-manager-yarn
Action requiredUntil the upstream issue is fixed, pm verify-patches requires @yarnpkg/cli, @yarnpkg/core, and @yarnpkg/plugin-patch as root development dependencies, plus the resolution "@yarnpkg/core/got": "npm:^11.8.6".

The change avoids an upstream installation failure.

Show release-note lines
- `@backstage/cli-module-package-manager-yarn` makes its Yarn dependencies optional peers to avoid an upstream installation failure. Until fixed upstream, users of `pm verify-patches` must add `@yarnpkg/cli`, `@yarnpkg/core`, and `@yarnpkg/plugin-patch` as root development dependencies, along with the resolution `"@yarnpkg/core/got": "npm:^11.8.6"`.
github.com/backstage/backstage/releases/tag/v1.57.0

CodeOwnersProcessor and AnnotateScmSlugEntityProcessor exports removed

Affectsbackends using CodeOwnersProcessor or AnnotateScmSlugEntityProcessor from this package(Inferred)
Action requiredTo retain either processor's behavior, the corresponding community module must be installed in the backend package and registered with backend.add(import('<module-package>')); the old custom processor registration must be removed to avoid registering it twice.
Show release-note lines
## Migrating removed processors
`CodeOwnersProcessor` and `AnnotateScmSlugEntityProcessor` are no longer exported
by this package. Use the corresponding community modules to retain their behavior:
- `CodeOwnersProcessor`: [`@backstage-community/plugin-catalog-backend-module-codeowners`](https://github.com/backstage/community-plugins/tree/main/workspaces/catalog/plugins/catalog-backend-module-codeowners)
- `AnnotateScmSlugEntityProcessor`: [`@backstage-community/plugin-catalog-backend-module-annotate-scm-slug`](https://github.com/backstage/community-plugins/tree/main/workspaces/catalog/plugins/catalog-backend-module-annotate-scm-slug)
Install the module you need in your backend package and register it with
`backend.add(import('<module-package>'))`. Remove your custom registration of the
old processor to avoid registering it twice. If you need to configure a processor
explicitly, follow the replacement module's documentation.
github.com/backstage/backstage/blob/master/plugins/catalog-backend/README.md

Deprecations5

AnyApiRef and AnyApiFactory deprecated

Affectscode using AnyApiRef or AnyApiFactory(Inferred)
Removed innot stated

The aliases remain available for compatibility; ApiRef and ApiFactory without type arguments are the preferred forms.

Show release-note lines
- `AnyApiRef` and `AnyApiFactory` are deprecated in favor of `ApiRef` and `ApiFactory` without type arguments. The deprecated aliases remain available for compatibility.
github.com/backstage/backstage/releases/tag/v1.57.0

Individual core Utility API references deprecated in favor of coreApis

Affectsfront-end system setups using core Utility API references(Inferred)
Removed innot stated

Existing individual references and the grouped form refer to the same API reference, so existing factories and implementations remain compatible during migration. Provider-specific authentication references remain separate.

Show release-note lines
The front-end system now groups its core Utility API references in `coreApis`, imported from `@backstage/frontend-plugin-api`. Access APIs through calls such as `useApi(coreApis.config)`, `useApi(coreApis.identity)`, and `useApi(coreApis.toast)`.
Individual references with namespace equivalents, such as `configApiRef`, are deprecated. Both forms refer to the same API reference, so existing factories and implementations remain compatible during migration. Provider-specific authentication references remain separate. See [consuming Utility APIs](../frontend-system/utility-apis/03-consuming.md#core-utility-apis) for usage examples and migration guidance.
github.com/backstage/backstage/releases/tag/v1.57.0

TechDocs CLI MkDocs flags deprecated in favor of replacements

AffectsTechDocs CLI configurations or automation using --mkdocs-port, --mkdocs-config-file-name or --mkdocs-parameter-*
Removed innot stated

Using a deprecated flag produces a warning. If its replacement is also set, the deprecated flag is ignored.

Show release-note lines
The TechDocs CLI supports Zensical in `serve`, `serve:raw`, and `generate`, including live reload in the preview app. Docker images are now selected per engine, and MkDocs previews use `spotify/techdocs:v1.2.8` rather than `latest`. The `--mkdocs-port`, `--mkdocs-config-file-name`, and `--mkdocs-parameter-*` flags are deprecated in favor of `--engine-port`, `--config-file-name`, and `--parameter-*`. An alpha entry point in `@backstage/plugin-techdocs-node` provides building blocks for additional engines.
github.com/backstage/backstage/releases/tag/v1.57.0

BitbucketCloudClient.searchCode deprecated; workspace search method added

Affectscallers of BitbucketCloudClient.searchCode or users needing workspace code search(Inferred)
Removed innot stated

The method uses a Bitbucket Cloud endpoint scheduled for removal on 2026-11-15. The workspace code search API requires a user credential with the read:repository:bitbucket and read:workspace:bitbucket scopes.

Show release-note lines
When code search is unavailable or rejects the configured credentials, discovery falls back to checking catalog files through the source API. Adding `read:workspace:bitbucket` to an API token restores workspace code search. `BitbucketCloudClient.searchCode` is deprecated in favor of `searchWorkspaceCode`.
github.com/backstage/backstage/releases/tag/v1.57.0

Deprecation notices for @backstage/core-components exports

Affectssetups using the affected @backstage/core-components exports
Removed innot stated

The exports remain available in this release. Migration guidance points framework-managed pages with page and sub-page extensions to PageLayout, standalone layouts to compositions with @backstage/ui, and app-customizable icons to coreApis.icons.

Show release-note lines
Many `@backstage/core-components` exports now have deprecation notices pointing to Backstage UI replacements or compositions. These include page shells, headers, tabs, links, cards, selectors, avatars, alert displays, and icon wrappers. Existing exports and behavior remain available. Follow each component's migration notice when adapting props, document titles, routing, and layout; these are not all direct import replacements.
Use page and sub-page extensions with `PageLayout` for framework-managed pages, compose `@backstage/ui` for standalone layouts, and use `coreApis.icons` for app-customizable icons.
github.com/backstage/backstage/releases/tag/v1.57.0

Important fixes25Silent failure1

  • Case-insensitive entities/by-refs lookup fixed
    Affectscatalog lookups through entities/by-refs

    Previously, a reference with different casing from the stored lowercase reference returned null even when the entity existed; it now resolves to that entity.

    Malformed predicates that combine `$all`, `$any`, or `$not` with other keys in the same object, or pass non-array operands to `$all` or `$any`, now receive a 400 response instead of silently ignoring parts of the filter. Entity lookups through `entities/by-refs` now match case-insensitively, consistent with the entity reference contract. Contributed by [@chicobento](https://github.com/chicobento) in [#36744](https://github.com/backstage/backstage/pull/36744).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • OIDC token expiration now honors auth.backstageTokenExpiration
    AffectsAuth backend OIDC token issuance with auth.backstageTokenExpiration configured

    Previously, the OIDC service issued tokens with a fixed one-hour lifetime even when the setting specified another duration; it now honors that setting, which defaults to 3600 seconds and allows values from 600 to 86400 seconds.

    OAuth access and ID tokens issued by the auth backend now respect `auth.backstageTokenExpiration` instead of always expiring after one hour. Contributed by [@Retr0-XD](https://github.com/Retr0-XD) in [#35325](https://github.com/backstage/backstage/pull/35325).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Empty-page and NaN range fix for useTable paginationSilent failure
    Affectscomplete-mode useTable instances that switch paginationOptions.type from none to page after mounting

    Before this fix, that switch could leave the table with no rows and a NaN - NaN of N range, without warning. The table now displays the first page.

    Alongside the routing changes described above, `useTable` no longer shows an empty page with a `NaN` range when pagination is enabled after mounting. Contributed by [@GabDug](https://github.com/GabDug) in [#35881](https://github.com/backstage/backstage/pull/35881). See the [BUI changelog](https://ui.backstage.io/changelog) for the full list of updates.
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Cross-plugin Valkey cache key collisions fixed
    Affectssetups using the Valkey cache store (backend.cache.store: valkey)

    When two plugins used the same cache key, each could read or overwrite the other's value. Plugin-namespaced keys now isolate their caches; values are rebuilt as plugins write, while old entries with a TTL remain until expiration and entries without a TTL or old per-plugin key index sets remain until manually removed.

    - The Valkey cache store now separates keys by plugin. Existing cache values are rebuilt under new keys, and old entries without a time to live need manual cleanup. Contributed by [@pavstev](https://github.com/pavstev) in [#36584](https://github.com/backstage/backstage/pull/36584).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Toast display no longer replays dismissed toasts
    Affectsapps using the toast display

    A toast posted via ToastApi could reappear after it was dismissed by the close button or timeout and ToastDisplay remounted, such as after a theme switch. Now dismissed toasts are removed from the replay buffer, while non-dismissed toasts remain available for replay.

    - Dismissed toasts no longer reappear when the toast display remounts, such as after a theme change. Contributed by [@abdul-karim-mia](https://github.com/abdul-karim-mia) in [#36813](https://github.com/backstage/backstage/pull/36813).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Scaffolder task-log redaction compares object properties by key
    AffectsScaffolder backend task logs for action inputs with secret-dependent object properties and public values

    When rendering without secrets omitted a secret-dependent object property, positional comparison could mistake later public values for secrets and mask them; a public URL after a secret token could disappear. Object properties are now compared by key while arrays remain compared by position, keeping public values visible and secret-derived keys and values redacted.

    - Scaffolder task controls retain their chosen visibility after completion, log redaction preserves public values, and custom task permission rules are honored. Contributed by [@ebarault](https://github.com/ebarault) in [#36472](https://github.com/backstage/backstage/pull/36472), [#36477](https://github.com/backstage/backstage/pull/36477), and [#36210](https://github.com/backstage/backstage/pull/36210).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • BUI SelectWidget multi-select rendering fixed
    AffectsSoftware Template forms using the BUI theme with SelectWidget fields defined as type: array, uniqueItems: true, and items.enum

    These fields previously rendered as single-select, and focus and blur passed raw form values rather than indices to enumOptionsValueForIndex. They now allow multiple enum selections, while the single-select path remains unchanged.

    - BUI template forms have clearer array item headings, more accessible item controls, and working enum multi-select fields. Contributed by [@ebarault](https://github.com/ebarault) in [#36469](https://github.com/backstage/backstage/pull/36469), and [@Dasmat13](https://github.com/Dasmat13) in [#36423](https://github.com/backstage/backstage/pull/36423) and [#36331](https://github.com/backstage/backstage/pull/36331).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • DevTools scheduled tasks loading display fixed
    AffectsDevTools scheduled tasks view(Inferred)

    After the initial load, switching plugins while tasks were loading could leave the previous plugin’s data visible without a progress indicator. The view now shows progress until loading finishes, then displays the table.

    - DevTools displays backend errors and loading progress for scheduled tasks. Contributed by [@Dasmat13](https://github.com/Dasmat13) in [#36533](https://github.com/backstage/backstage/pull/36533).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Nested template filename generation fixed on Windows
    AffectsWindows use of backstage-cli new with templates containing files in nested subdirectories(Inferred)

    Backslashes in relative paths could escape Handlebars braces, leaving {{extensionName}} uninterpolated and stripping a path separator, which corrupted generated filenames. The CLI now uses forward slashes for nested template paths, allowing Handlebars to interpolate variables and preserve the intended nested filenames.

    - Package scaffolding preserves existing `CODEOWNERS` content, reuses newer compatible dependency ranges, and fixes corrupted nested filenames on Windows. The Windows fix was contributed by [@HLoc26](https://github.com/HLoc26) in [#35242](https://github.com/backstage/backstage/pull/35242).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Generated API declaration overwrites fixed
    Affectssetups generating API reference pages with declarations whose names collide by case or declaration kind(Inferred)

    Previously, generated API reference pages overwrote declarations when their names collided by case or declaration kind. They now retain those declarations instead.

    - Generated API reference pages no longer overwrite declarations whose names collide by case or declaration kind.
    github.com/backstage/backstage/releases/tag/v1.57.0
  • LDAP provider refresh connections closed after each refresh
    AffectsLDAP entity provider refreshes that open LDAP connections

    By default, the provider reads users and groups in parallel, opening two connections and binds per refresh.

    The entity provider also reads users and groups in parallel by default, opening two connections and binds per refresh. Set `disableParallelReads: true` on the provider to retain sequential reads when directory connection limits require it. Connections are closed after each refresh.
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Signals backend first WebSocket connection fix
    Affectssetups using the Signals backend

    Previously, a first WebSocket connection through the Signals backend required an HTTP request before it could connect.

    The Signals backend uses this API, fixing first connections that previously required an HTTP request before the WebSocket could connect. Existing server upgrade listeners can coexist during migration, but plugins that handle upgrades only through Express, such as the Kubernetes proxy, must migrate to the router API when the framework's server-level listener is active. Otherwise, unmatched upgrades receive a 404 response when it is the only server-level listener. See the [HTTP router service documentation](../backend-system/core-services/http-router.md).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Bitbucket Cloud catalog discovery switches to workspace code search
    Affectssetups using the Bitbucket Cloud entity provider for catalog discovery(Inferred)

    The previous code-search endpoint was retired on November 15, 2026. Workspace code search requires a credential that identifies a user and both read:repository:bitbucket and read:workspace:bitbucket scopes; if search is unavailable or rejects the credentials, discovery falls back to checking catalog files through the source API while finding the same locations for the same configuration.

    The Bitbucket Cloud entity provider now uses the workspace code search API following retirement of the previous endpoint on November 15, 2026. Workspace code search requires a credential that identifies a user, such as an Atlassian account email as `username` with an API `token`, and both `read:repository:bitbucket` and `read:workspace:bitbucket` scopes. App passwords, legacy OAuth consumers, API keys, and API tokens missing the workspace scope are rejected by that API.
    github.com/backstage/backstage/releases/tag/v1.57.0
  • PostgreSQL catalog facet and total-count queries sped up
    AffectsPostgreSQL catalog facets and queryEntities() total-item counts

    On production-scale catalogs, conditional permission policies that produced $any or $not filters could make these queries take 10–25 seconds or time out; long value lists such as ownership claims also benefited. The queries now use entity-ID set operations and return the same results as before where the previous implementation completed.

    Catalog queries on PostgreSQL are faster when conditional permission policies produce `$any` or `$not` filters, or match fields against long lists of values such as ownership claims. Facet and total count queries also benefit. Contributed in part by [@drodil](https://github.com/drodil) in [#36518](https://github.com/backstage/backstage/pull/36518).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Cross-tab OAuth refresh race fixed
    AffectsBackstage frontend sessions in browsers with the Web Locks API

    Concurrent tabs could refresh the same cookie before a rotated refresh token reached the browser, causing sign-in prompts. With Web Locks support, only one refresh for the same provider endpoint runs at a time across tabs; without it, refreshes can still run concurrently.

    Background OAuth refreshes no longer prompt users to sign in again after transient network failures. Contributed by [@csuich2](https://github.com/csuich2) in [#35003](https://github.com/backstage/backstage/pull/35003). Refresh requests are also coordinated across tabs in browsers with the Web Locks API, avoiding competing refreshes with providers that rotate refresh tokens. Contributed by [@hudsonb](https://github.com/hudsonb) in [#36615](https://github.com/backstage/backstage/pull/36615).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Test rendering helpers preserve extensions with a test plugin
    Affectstest rendering helpers used with a plugin named test in features
    - Test rendering helpers preserve their test extensions when a plugin named `test` is included in `features`.
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Dynamic backend plugin package resolution fixed
    Affectssetups using dynamic backend plugins, including pnpm isolated linker setups and Windows plugins inside the Backstage root

    Previously, plugins could not resolve shared backend packages absent from the root node_modules; on Windows, plugins inside the Backstage root also could not find the root node_modules without NODE_PATH. The loader now searches the backend package and its own lookup chain after existing locations, which remain first; with hoist: false, it finds only direct dependencies of the backend package and the loader.

    - Dynamic backend plugins can resolve shared packages with the isolated pnpm linker. Contributed by [@sebdanielsson](https://github.com/sebdanielsson) in [#36229](https://github.com/backstage/backstage/pull/36229).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Scaffolder custom task-rule authorization and filtering fixed
    AffectsScaffolder backends with registered custom scaffolder-task permission rules

    When a permission policy condition used a registered custom scaffolder-task rule for task authorization or task-list filtering, the routes or filtering returned a 500 instead of applying it. These rules are now evaluated for individual task access and list filtering; registering a rule alone does not grant access unless the permission policy returns a condition that uses it.

    - Scaffolder task controls retain their chosen visibility after completion, log redaction preserves public values, and custom task permission rules are honored. Contributed by [@ebarault](https://github.com/ebarault) in [#36472](https://github.com/backstage/backstage/pull/36472), [#36477](https://github.com/backstage/backstage/pull/36477), and [#36210](https://github.com/backstage/backstage/pull/36210).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Confluence to Markdown attachment download handling fixed
    AffectsConfluence to Markdown Scaffolder action attachment downloads

    When an attachment download failed partway through, the Scaffolder step hung and left the file handle open. Such failures now fail the task with the underlying error, and downloaded files are closed on every path.

    - Confluence attachment download failures now fail the task rather than leaving it hanging, and downloaded files are closed correctly. Contributed by [@rowmanempire](https://github.com/rowmanempire) in [#36745](https://github.com/backstage/backstage/pull/36745).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Broadcast notification status preservation fixed
    Affectssetups using broadcast notifications in the notifications backend(Inferred)

    Marking a broadcast notification read or unread could erase its saved status, while saving or unsaving it could erase its read status. These updates now leave the other status unchanged for each user.

    - Broadcast notifications preserve their read and saved states independently. Contributed by [@FayezBast](https://github.com/FayezBast) in [#36535](https://github.com/backstage/backstage/pull/36535).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • DevTools scheduled tasks view now displays returned errors
    Affectsthe DevTools scheduled tasks view(Inferred)

    When useScheduledTasks returned a backend error, authorization denial (403), or network failure, users saw a misleading “no scheduled tasks” message that could suggest a typo or an empty task list.

    - DevTools displays backend errors and loading progress for scheduled tasks. Contributed by [@Dasmat13](https://github.com/Dasmat13) in [#36533](https://github.com/backstage/backstage/pull/36533).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Localized PostgreSQL unique-violation fallback fixed in catalog ingestion
    AffectsCatalog ingestion with PostgreSQL localized error messages (lc_messages)

    When duplicate entity references caused a PostgreSQL unique violation, the fast-insert path rethrew the error instead of retrying with individual updates. It now uses that fallback; SQLite and MySQL message-based detection is unchanged.

    - PostgreSQL unique constraint violations are detected correctly when database error messages are localized, allowing catalog ingestion to fall back to individual updates for duplicate entity references. Contributed by [@harshitsharmaaaa](https://github.com/harshitsharmaaaa) in [#36921](https://github.com/backstage/backstage/pull/36921).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Backstage CLI start commands now accept repeated --require flags
    Affectsmultiple --require options in backstage-cli package start or backstage-cli repo start, including backend package start scripts(Inferred)

    Previously, only one --require option was allowed, and repo start forwarded only the last option from a backend package's start script. Repeated options are now accepted, and repo start forwards all of them from the script.

    - CLI commands preserve their exit codes, and package startup supports repeated `--import` and `--require` flags. Flag support contributed by [@dotboris](https://github.com/dotboris) in [#36647](https://github.com/backstage/backstage/pull/36647).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • CLI module transform no longer forces typeless JavaScript to CommonJS
    AffectsLocal development loading JavaScript from packages without a type field through the CLI's Node.js transform

    The transform previously treated those JavaScript files as CommonJS, breaking named imports from ES module entry points. Node.js now detects their format so named imports load correctly; TypeScript files in those packages remain treated as CommonJS.

    - The CLI handles JavaScript ES modules in packages without a `type` field correctly. Contributed by [@vibbix](https://github.com/vibbix) in [#36604](https://github.com/backstage/backstage/pull/36604).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • GitHub URL reader drains failed response bodies
    Affectssetups using the GitHub URL reader

    When a failed GitHub request returned a body too large for the stream buffers, the reader left the response incomplete and its socket open until restart, leaking connections and memory. It now drains the body before throwing, so the response completes and the connection is released.

    - The GitHub URL reader releases connections after failed requests with large error bodies, avoiding connection and memory leaks during outages. Contributed by [@dddimcha](https://github.com/dddimcha) in [#36830](https://github.com/backstage/backstage/pull/36830).
    github.com/backstage/backstage/releases/tag/v1.57.0

Enhancements28

  • Routing library adapters for front-end system pages
    The front-end system now owns the browser history, while each page can choose its own routing library. Three new adapter packages support React Router v6, React Router v7, and TanStack Router, including pages that host sub-pages using a different library. Existing pages retain implicit React Router v6 compatibility. Framework navigation APIs such as `useAppNavigate`, `useAppLocation`, and `RouterLink` let plugins navigate without depending on a page's router. Router and component-library integrations use the stable `@backstage/frontend-plugin-api/routing` entry point, while app history is available through `coreApis.appHistory` in the main entry point.
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Router-independent navigation APIs for plugins
    The front-end system now owns the browser history, while each page can choose its own routing library. Three new adapter packages support React Router v6, React Router v7, and TanStack Router, including pages that host sub-pages using a different library. Existing pages retain implicit React Router v6 compatibility. Framework navigation APIs such as `useAppNavigate`, `useAppLocation`, and `RouterLink` let plugins navigate without depending on a page's router. Router and component-library integrations use the stable `@backstage/frontend-plugin-api/routing` entry point, while app history is available through `coreApis.appHistory` in the main entry point.
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Stable routing entry point and app history access
    The front-end system now owns the browser history, while each page can choose its own routing library. Three new adapter packages support React Router v6, React Router v7, and TanStack Router, including pages that host sub-pages using a different library. Existing pages retain implicit React Router v6 compatibility. Framework navigation APIs such as `useAppNavigate`, `useAppLocation`, and `RouterLink` let plugins navigate without depending on a page's router. Router and component-library integrations use the stable `@backstage/frontend-plugin-api/routing` entry point, while app history is available through `coreApis.appHistory` in the main entry point.
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Suspense and error handling at page extension boundaries
    Page extension boundaries provide Suspense and error handling; consumers outside those boundaries must provide their own. `TestApiProvider` and other mock API overrides accept synchronous mocks even for promise-valued APIs, so tests can keep synchronous assertions when rendering is otherwise synchronous. Promise-valued mocks are also supported, with `renderInTestApp` supplying an empty Suspense fallback while they resolve. Tests that relied on an ancestor boundary's loading UI may need updated assertions. See the [Utility API documentation](../frontend-system/utility-apis/02-creating.md) for lazy factories and migration guidance.
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Typed mocks and functional fakes for core APIs
    Test apps also use defaults designed for isolation: storage is kept in memory per app, toasts and errors are collected without displaying them, and alerts are no longer replayed to late subscribers. Tests that depend on browser storage, visible notifications, or global error handling need an explicit API implementation. Expanded `mockApis` helpers provide typed mocks and functional fakes for core APIs. Removed standalone mock types can be replaced with types derived from these helpers, such as `ReturnType<typeof mockApis.analytics>`.
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Test render helpers return an apis holder
    Both render helpers now return an `apis` holder with access to the same Utility API instances used by components, including test overrides. For navigation tests, use `apis.get(coreApis.appHistory)` to access the app history. Page matching uses framework routing; wrap test elements in a page adapter when they need routing-library context. See the [navigation testing guide](../frontend-system/building-plugins/02-testing.md#navigation-and-app-history).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Pre-registered OAuth clients in the auth backend

    To use auth.staticClients

    Pre-registered clients support a fixed client ID, an optional secret, and exact redirect URIs, allowing integrations that do not support CIMD to authenticate. Clients with a secret must authenticate for both code exchanges and refreshes. Removing a client from the configuration rejects its outstanding authorization codes and refresh tokens. See [pre-registered clients](../ai/mcp-actions.md#pre-registered-clients).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Unauthenticated event configuration for GitHub, GitLab, and Azure DevOps modules

    To use Set dangerouslyAllowUnauthenticatedEvents: true under the module configuration to enable unauthenticated events.

    For development setups that deliberately accept unauthenticated events, each module provides an explicit `dangerouslyAllowUnauthenticatedEvents: true` option. Custom users of `createGitlabTokenValidator` must also supply its new `logger` argument. See the configuration sections for the [GitHub](https://github.com/backstage/backstage/blob/master/plugins/events-backend-module-github/README.md#configuration), [GitLab](https://github.com/backstage/backstage/blob/master/plugins/events-backend-module-gitlab/README.md#configuration), and [Azure DevOps](https://github.com/backstage/backstage/blob/master/plugins/events-backend-module-azure/README.md#configuration) modules.
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Token authentication for WebSocket upgrade routes

    To use Use the backend HTTP router service's addWebSocketHandler method to register WebSocket upgrade routes.

    The backend HTTP router services now provide `addWebSocketHandler` for registering WebSocket upgrade routes. Routes require token authentication by default, and browser clients can pass bearer tokens through the WebSocket protocol header. Cookie authentication is not supported. Custom implementations of `HttpRouterService` and `RootHttpRouterService` must implement the new method; the backend test utilities support it too.
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Translated titles for page and sub-page blueprints
    Page and sub-page blueprints, along with `EntityContentBlueprint`, now accept typed translation message selections as titles. Select a message by calling its translation ref, for example `myTranslationRef('page.title')`. Navigation, page headers, tabs, and breadcrumbs render the translated title. Selections must not require formatting values, and resolved translations take precedence over configured static titles in every language.
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Conditional parameter steps in Software Templates

    To use A when condition on a parameter step

    Software Templates can now show or hide whole parameter steps based on earlier answers using a `when` condition, such as `${{ parameters.cloudProvider === 'AWS' }}`. The frontend wizard and backend validation evaluate the same conditions, and values from hidden steps are excluded from the task parameters. Fields referenced by conditions should be validated by an earlier unconditional step. See [conditional parameter steps](../features/software-templates/writing-templates.md#conditionally-showing-parameter-steps).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Viewer-aware filtering for the template list
    Apps using the front-end system can filter the template list based on identity, catalog data, or other viewer-specific state through `ScaffolderTemplateFilterBlueprint`. This extension is not available in the old front-end system. Contributed by [@Dasmat13](https://github.com/Dasmat13) in [#36096](https://github.com/backstage/backstage/pull/36096).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Backend offline-session revocation endpoint

    To use auth.experimentalRefreshToken.enabled must be set

    Sign-in resolvers now issue canonical, deduplicated entity references in user token claims, and `auth logout` correctly revokes the CLI refresh token. A service-authenticated `POST /v1/offline-sessions/revoke` endpoint lets backends revoke all of a user's offline sessions when `auth.experimentalRefreshToken.enabled` is set. Cursor clients are allowed to use CIMD by default, contributed by [@pjohannis](https://github.com/pjohannis) in [#36568](https://github.com/backstage/backstage/pull/36568).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Cursor client IDs added to the default CIMD allowlist

    To use CIMD must be enabled; if allowedClientIdPatterns is overridden, it must include https://cursor.com/oauth/mcp-client.json.

    Sign-in resolvers now issue canonical, deduplicated entity references in user token claims, and `auth logout` correctly revokes the CLI refresh token. A service-authenticated `POST /v1/offline-sessions/revoke` endpoint lets backends revoke all of a user's offline sessions when `auth.experimentalRefreshToken.enabled` is set. Cursor clients are allowed to use CIMD by default, contributed by [@pjohannis](https://github.com/pjohannis) in [#36568](https://github.com/backstage/backstage/pull/36568).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Client certificate credentials for Azure DevOps App Registrations

    To use Configure ClientCertificate with clientId, tenantId, and exactly one of clientCertificate (inline PEM including the private key) or clientCertificatePath.

    Azure DevOps integrations can authenticate an App Registration with a certificate instead of a client secret. Configure the `ClientCertificate` credential kind with `clientId`, `tenantId`, and either `clientCertificate` containing the PEM certificate and private key, or `clientCertificatePath`.
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Static error type guards in @backstage/errors
    ### Error type guards across package copies
    `@backstage/errors` now provides static type guards such as `AuthenticationError.is(value)` and `ResponseError.is(value)` to narrow unknown errors across package copies by checking their name and basic shape:
    ```ts
    import { ResponseError } from '@backstage/errors';
    if (ResponseError.is(error)) {
      console.log(error.statusCode);
    }
    ```
    Use `isErrorWithName(value, name)` to implement name-based guards for custom errors.
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Broader API reference ID format support
    - API reference IDs now use the plugin ID format for each dot-separated component, accepting mixed case and numeric dash groups such as `plugin.example-2.todos`.
    github.com/backstage/backstage/releases/tag/v1.57.0
  • beginAt timestamps for plugin and module startup results
    - Backend startup results include optional `beginAt` timestamps for plugin and module initialization, separating initialization time from time spent waiting for dependencies. Contributed by [@hudsonb](https://github.com/hudsonb) in [#36326](https://github.com/backstage/backstage/pull/36326).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Dynamic plugins support FrontendFeatureLoader exports

    To use The dynamic plugin’s exposed entry point must default-export a FrontendFeatureLoader; the loader can select and return frontend features at load time, including nested FrontendFeatureLoader values.

    - Dynamic frontend plugins can export a `FrontendFeatureLoader`. Contributed by [@hopehadfield](https://github.com/hopehadfield) in [#35687](https://github.com/backstage/backstage/pull/35687).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • GitLab branch autocomplete in RepoBranchPicker

    To use GitLab Scaffolder backend module, requestUserCredentials, and a repository field named repoUrl

    - Software Templates supports GitLab branch autocompletion in `RepoBranchPicker`. Contributed by [@ebarault](https://github.com/ebarault) in [#36086](https://github.com/backstage/backstage/pull/36086).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • GitHub Scaffolder action for repository ruleset creation

    To use Use the github:repo:rulesets:create action in a Software Template to create repository rulesets.

    - The new `github:repo:rulesets:create` action lets Software Templates create GitHub repository rulesets, including rules and bypass actors in the GitHub REST API format. Contributed by [@rbstp](https://github.com/rbstp) in [#36776](https://github.com/backstage/backstage/pull/36776).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • GitHub org entity providers can fetch public emails with GitHub Apps

    To use Set fetchEmailForGithubApps to true; the GitHub App must be able to read user emails.

    - GitHub organization providers can request public emails when authenticating with a GitHub App using `fetchEmailForGithubApps`. Enable it only after checking that your GitHub instance supports the query. Contributed by [@vinzscam](https://github.com/vinzscam) in [#36736](https://github.com/backstage/backstage/pull/36736).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Direct AWS account credential selection for Kubernetes clusters

    To use Set kubernetes.io/aws-account-id in the cluster's auth metadata to use that account's credentials directly.

    - AWS Kubernetes clusters can use configured account credentials directly through `kubernetes.io/aws-account-id`. The S3 URL reader also avoids assuming an account's already-assumed role a second time. Contributed in part by [@hudsonb](https://github.com/hudsonb) in [#35963](https://github.com/backstage/backstage/pull/35963).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Backstage CLI startup commands accept --import
    - CLI commands preserve their exit codes, and package startup supports repeated `--import` and `--require` flags. Flag support contributed by [@dotboris](https://github.com/dotboris) in [#36647](https://github.com/backstage/backstage/pull/36647).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Backstage apps apply the selected color scheme before loading

    To use For existing apps: theme.js and the color-scheme meta tag and script in packages/app/public/index.html.

    - New apps apply their selected light or dark theme before loading, avoiding an initial light background for dark themes. Contributed by [@carlerikjohan](https://github.com/carlerikjohan) in [#36162](https://github.com/backstage/backstage/pull/36162).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Parsed query strings included in event request validator requests
    - Event request validators receive parsed query parameters and can specify a response content type when rejecting a request. Contributed by [@stanislav-c](https://github.com/stanislav-c) in [#36488](https://github.com/backstage/backstage/pull/36488).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Custom content types for request rejection payloads

    To use The optional contentType option for non-default content types

    - Event request validators receive parsed query parameters and can specify a response content type when rejecting a request. Contributed by [@stanislav-c](https://github.com/stanislav-c) in [#36488](https://github.com/backstage/backstage/pull/36488).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • File URL support in resolvePackagePath
    - `resolvePackagePath` accepts file URL strings such as `import.meta.url`, and backend plugins resolve their database migrations relative to their own package without requiring package-name resolution.
    github.com/backstage/backstage/releases/tag/v1.57.0
Other changes34
  • Public APIs for four frontend packages are now stable
    The front-end system reaches its 1.0 milestone in this release! The public APIs of `@backstage/frontend-plugin-api`, `@backstage/frontend-app-api`, `@backstage/frontend-test-utils`, and `@backstage/frontend-dev-utils` are now stable under the [package versioning policy](../overview/versioning-policy.md#package-versioning-policy).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Translated titles wait for initial language selection
    `TranslationRef` values are now callable functions and must be treated as opaque values rather than cloned or checked for plain-object shape. Custom `TranslationApi` implementations must provide `t` in every translation snapshot, including while `ready` is false, using available messages and language fallbacks. Titles wait for the initial selected language and retain resolved values during later loads or failures, preserving page state. See the [internationalization guide](../frontend-system/building-plugins/07-internationalization.md).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Experimental Zensical engine for TechDocs
    The new `@backstage/plugin-techdocs-backend-module-zensical` module adds [Zensical](https://zensical.org) as an experimental TechDocs engine. Select it per entity with `backstage.io/techdocs-engine: zensical`, or set `techdocs.generator.defaultEngine: zensical`. MkDocs remains the default. See the [Zensical engine guide](../features/techdocs/engines-zensical.md) for setup and configuration.
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Zensical support in TechDocs CLI and preview live reload
    The TechDocs CLI supports Zensical in `serve`, `serve:raw`, and `generate`, including live reload in the preview app. Docker images are now selected per engine, and MkDocs previews use `spotify/techdocs:v1.2.8` rather than `latest`. The `--mkdocs-port`, `--mkdocs-config-file-name`, and `--mkdocs-parameter-*` flags are deprecated in favor of `--engine-port`, `--config-file-name`, and `--parameter-*`. An alpha entry point in `@backstage/plugin-techdocs-node` provides building blocks for additional engines.
    github.com/backstage/backstage/releases/tag/v1.57.0
  • TechDocs CLI per-engine Docker image defaults
    The TechDocs CLI supports Zensical in `serve`, `serve:raw`, and `generate`, including live reload in the preview app. Docker images are now selected per engine, and MkDocs previews use `spotify/techdocs:v1.2.8` rather than `latest`. The `--mkdocs-port`, `--mkdocs-config-file-name`, and `--mkdocs-parameter-*` flags are deprecated in favor of `--engine-port`, `--config-file-name`, and `--parameter-*`. An alpha entry point in `@backstage/plugin-techdocs-node` provides building blocks for additional engines.
    github.com/backstage/backstage/releases/tag/v1.57.0
  • TechDocs engine building blocks in the /alpha entry point
    The TechDocs CLI supports Zensical in `serve`, `serve:raw`, and `generate`, including live reload in the preview app. Docker images are now selected per engine, and MkDocs previews use `spotify/techdocs:v1.2.8` rather than `latest`. The `--mkdocs-port`, `--mkdocs-config-file-name`, and `--mkdocs-parameter-*` flags are deprecated in favor of `--engine-port`, `--config-file-name`, and `--parameter-*`. An alpha entry point in `@backstage/plugin-techdocs-node` provides building blocks for additional engines.
    Contributed by [@byan1197](https://github.com/byan1197) in [#36159](https://github.com/backstage/backstage/pull/36159). [earlier release v1.56.3]
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Bitbucket Cloud entity provider catalog discovery fallback
    When code search is unavailable or rejects the configured credentials, discovery falls back to checking catalog files through the source API. Adding `read:workspace:bitbucket` to an API token restores workspace code search. `BitbucketCloudClient.searchCode` is deprecated in favor of `searchWorkspaceCode`.
    github.com/backstage/backstage/releases/tag/v1.57.0
  • OAuth refresh no longer clears sessions after transient network failures
    Background OAuth refreshes no longer prompt users to sign in again after transient network failures. Contributed by [@csuich2](https://github.com/csuich2) in [#35003](https://github.com/backstage/backstage/pull/35003). Refresh requests are also coordinated across tabs in browsers with the Web Locks API, avoiding competing refreshes with providers that rotate refresh tokens. Contributed by [@hudsonb](https://github.com/hudsonb) in [#36615](https://github.com/backstage/backstage/pull/36615).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Azure DevOps URL reader startup warning for Azure DevOps Services personal access tokens
    The Azure DevOps URL reader now warns at startup when a personal access token is configured for Azure DevOps Services. Global personal access tokens retire on January 27, 2027, and organization-scoped tokens are deprecated in favor of Microsoft Entra ID credentials. See the [retirement announcement](https://devblogs.microsoft.com/devops/retirement-of-global-personal-access-tokens-in-azure-devops/) when planning the migration.
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Header tabs scroll within a single row
    `Header` tabs stay in a single scrolling row when they do not fit, instead of causing the entire page to scroll horizontally. Overflow fades, pointer scroll buttons, and automatic scrolling keep the active tab visible. Contributed by [@carlerikjohan](https://github.com/carlerikjohan) in [#36177](https://github.com/backstage/backstage/pull/36177).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Catalog EntityNotFound switches to Backstage UI
    The catalog entity-not-found display now uses Backstage UI, contributed by [@Abhijnya002](https://github.com/Abhijnya002) in [#36777](https://github.com/backstage/backstage/pull/36777). The catalog import pull request preview card has also migrated, contributed by [@rickylandino](https://github.com/rickylandino) in [#36835](https://github.com/backstage/backstage/pull/36835).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Catalog import pull request preview card switches to Backstage UI
    The catalog entity-not-found display now uses Backstage UI, contributed by [@Abhijnya002](https://github.com/Abhijnya002) in [#36777](https://github.com/backstage/backstage/pull/36777). The catalog import pull request preview card has also migrated, contributed by [@rickylandino](https://github.com/rickylandino) in [#36835](https://github.com/backstage/backstage/pull/36835).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • App backend startup checks load cached frontend asset paths only
    - App backend startup uses less memory and database traffic when checking cached assets. Contributed by [@hudsonb](https://github.com/hudsonb) in [#36458](https://github.com/backstage/backstage/pull/36458).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Deferred root element additions no longer remount apps
    - Apps no longer remount when deferred root elements are added during finalization, and swappable components preserve mounted state when their props change.
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Swappable components preserve mounted state across prop changes
    - Apps no longer remount when deferred root elements are added during finalization, and swappable components preserve mounted state when their props change.
    github.com/backstage/backstage/releases/tag/v1.57.0
  • TechDocs table of contents alignment fixed
    - The TechDocs table of contents stays aligned with the documentation on wide screens. Contributed by [@bhargavikvmpl-2001](https://github.com/bhargavikvmpl-2001) in [#36216](https://github.com/backstage/backstage/pull/36216).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Scaffolder task pages preserve button-bar visibility after completion
    - Scaffolder task controls retain their chosen visibility after completion, log redaction preserves public values, and custom task permission rules are honored. Contributed by [@ebarault](https://github.com/ebarault) in [#36472](https://github.com/backstage/backstage/pull/36472), [#36477](https://github.com/backstage/backstage/pull/36477), and [#36210](https://github.com/backstage/backstage/pull/36210).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • BUI array item headings use item titles
    - BUI template forms have clearer array item headings, more accessible item controls, and working enum multi-select fields. Contributed by [@ebarault](https://github.com/ebarault) in [#36469](https://github.com/backstage/backstage/pull/36469), and [@Dasmat13](https://github.com/Dasmat13) in [#36423](https://github.com/backstage/backstage/pull/36423) and [#36331](https://github.com/backstage/backstage/pull/36331).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • BUI form screen reader announcements and labels improved
    - BUI template forms have clearer array item headings, more accessible item controls, and working enum multi-select fields. Contributed by [@ebarault](https://github.com/ebarault) in [#36469](https://github.com/backstage/backstage/pull/36469), and [@Dasmat13](https://github.com/Dasmat13) in [#36423](https://github.com/backstage/backstage/pull/36423) and [#36331](https://github.com/backstage/backstage/pull/36331).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • GitLab Scaffolder file handling fixed for failed tree listings
    - GitLab publish actions check individual files if listing the repository tree fails, avoiding incorrect file-creation attempts. Contributed by [@leneti](https://github.com/leneti) in [#36486](https://github.com/backstage/backstage/pull/36486).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • S3 URL reader avoids re-assuming an account role
    - AWS Kubernetes clusters can use configured account credentials directly through `kubernetes.io/aws-account-id`. The S3 URL reader also avoids assuming an account's already-assumed role a second time. Contributed in part by [@hudsonb](https://github.com/hudsonb) in [#35963](https://github.com/backstage/backstage/pull/35963).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Incremental ingestion no longer fails on repeated entity references
    - Incremental ingestion tolerates repeated entity references within a page or event, avoiding PostgreSQL upsert failures. Catalog placeholder processing also waits for all reads to settle before reporting an error.
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Catalog placeholder processing waits for reads before reporting errors
    - Incremental ingestion tolerates repeated entity references within a page or event, avoiding PostgreSQL upsert failures. Catalog placeholder processing also waits for all reads to settle before reporting an error.
    github.com/backstage/backstage/releases/tag/v1.57.0
  • PostgreSQL search indexing skips tsvector computation for unchanged documents
    - PostgreSQL search indexing skips full-text vector computation for unchanged documents. Contributed by [@Sriram-Nambiar](https://github.com/Sriram-Nambiar) in [#36473](https://github.com/backstage/backstage/pull/36473).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • SearchFilter.Autocomplete preserves typed text after selection
    - Search autocomplete with multiple selection no longer clears typed text after each keystroke. Contributed by [@dfl-aeb](https://github.com/dfl-aeb) in [#35967](https://github.com/backstage/backstage/pull/35967).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • World Clock widget switches to Backstage UI components and styles
    - The World Clock home widget now uses Backstage UI. Contributed by [@jzhn](https://github.com/jzhn) in [#36781](https://github.com/backstage/backstage/pull/36781).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Package scaffolding preserves existing CODEOWNERS content
    - Package scaffolding preserves existing `CODEOWNERS` content, reuses newer compatible dependency ranges, and fixes corrupted nested filenames on Windows. The Windows fix was contributed by [@HLoc26](https://github.com/HLoc26) in [#35242](https://github.com/backstage/backstage/pull/35242).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Backstage package scaffolding reuses newer compatible dependency ranges
    - Package scaffolding preserves existing `CODEOWNERS` content, reuses newer compatible dependency ranges, and fixes corrupted nested filenames on Windows. The Windows fix was contributed by [@HLoc26](https://github.com/HLoc26) in [#35242](https://github.com/backstage/backstage/pull/35242).
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Backend plugin migrations resolved relative to their package
    - `resolvePackagePath` accepts file URL strings such as `import.meta.url`, and backend plugins resolve their database migrations relative to their own package without requiring package-name resolution.
    github.com/backstage/backstage/releases/tag/v1.57.0
  • Unhandled-request test failures with MSW 3 fixed in registerMswTestHooks
    - `registerMswTestHooks` also fails tests on unhandled requests when used with MSW 3.
    github.com/backstage/backstage/releases/tag/v1.57.0
  • README guidance for the default catalog backend in created apps
    ## Installation
    This `@backstage/plugin-catalog-backend` package comes installed by default in
    any Backstage application created with `npx @backstage/create-app`, so
    installation is not usually required.
    To check if you already have the package, look under
    `packages/backend/package.json`, in the `dependencies` block, for
    `@backstage/plugin-catalog-backend`. The instructions below walk through
    restoring the plugin, if you previously removed it.
    ### Install the package
    ```bash
    # From your Backstage root directory
    yarn --cwd packages/backend add @backstage/plugin-catalog-backend
    ```
    Then add the plugin to your backend, typically in `packages/backend/src/index.ts`:
    
    ```ts
    const backend = createBackend();
    // ...
    backend.add(import('@backstage/plugin-catalog-backend'));
    github.com/backstage/backstage/blob/master/plugins/catalog-backend/README.md
  • Old backend catalog router wiring instructions
    In the old backend system there's a bit more wiring required. You'll need to
    create a file called `packages/backend/src/plugins/catalog.ts` with contents
    matching [catalog.ts in the create-app template](https://github.com/backstage/backstage/blob/ad9314d3a7e0405719ba93badf96e97adde8ef83/packages/create-app/templates/default-app/packages/backend/src/plugins/catalog.ts).
    With the `catalog.ts` router setup in place, add the router to
    `packages/backend/src/index.ts`:
    ```diff
    +import catalog from './plugins/catalog';
    async function main() {
      ...
      const createEnv = makeCreateEnv(config);
    +  const catalogEnv = useHotMemoize(module, () => createEnv('catalog'));
      const scaffolderEnv = useHotMemoize(module, () => createEnv('scaffolder'));
      const apiRouter = Router();
    +  apiRouter.use('/catalog', await catalog(catalogEnv));
      ...
      apiRouter.use(notFoundHandler());
    ```
    github.com/backstage/backstage/blob/master/plugins/catalog-backend/README.md
  • Catalog schema migration preserves and repairs indexes
    The migration preserves an existing valid index and repairs an invalid one left
    by an interrupted build. Reruns do not reset the generation counter. Reversing
    the migration discards this bookkeeping, not entity or search contents.
    github.com/backstage/backstage/blob/master/plugins/catalog-backend/README.md
  • Documentation for starting the catalog backend standalone or launching the example app
    This backend plugin can be started in a standalone mode from directly in this
    package with `yarn start`. However, it will have limited functionality and that
    process is most convenient when developing the catalog backend plugin itself.
    To evaluate the catalog and have a greater amount of functionality available,
    run the entire Backstage example application from the root folder:
    ```bash
    # in one terminal window, run this from from the very root of the Backstage project
    cd packages/backend
    yarn start
    ```
    This will launch both frontend and backend in the same window, populated with
    some example entities.
    github.com/backstage/backstage/blob/master/plugins/catalog-backend/README.md

Summaries are produced by AI, so they can be wrong, and they are provided without warranty.