RATATOSKRATATOSK
Sign in

Backstage

v1.54.0CI/CD & App Delivery
Aug 18, 2026

CHECK 15PLAN 2OTHER 183

A substantial feature, behavior, and maintenance release with breaking API and configuration changes, new APIs and templates, MCP and OAuth updates, AWS connection support, and scaffolder changes. Broad dependency updates and compatibility changes make migration and configuration review relevant for operators.

Check if affected (15)

  • breakingThe destructive attribute default

    Applies if you do not configure destructive.

    Read-only actions now default to non-destructive when destructive is omitted.

  • breakingThe Node.js snapshot default

    Applies if you run backends or tests.

    Starting backends or running tests no longer disables the Node.js snapshot by default.

  • breakingURL component matching for OAuth allowlists

    Applies if you configure OAuth redirect URI allowlists or client ID metadata document allowlists.

    In @backstage/plugin-auth-backend, OAuth redirect URI and client ID metadata document allowlists now match patterns against each URL component separately rather than the full URL string.

  • breakingThe config.schema option, removed

    Applies if you configure config.schema.

    The deprecated config.schema option for extensions and extension blueprints has been removed from @backstage/frontend-plugin-api.

  • breakingBackend-only exports from @backstage/connections

    Applies if you depend on @backstage/connections.

    Backend-only APIs and configuration types, including connectionsServiceRef, connectionsServiceFactory, DefaultConnectionsService, declareConnection, RootConnection, and AnyRootConnection, are no longer exported from @backstage/connections.

  • breakingThe connection lookup query object

    Applies if you use query.

    Connection lookups now take a query object instead of a url.

  • breakingThe RootConnectionAuth type rename

    Applies if you use RootConnectionAuth.

    The RootConnectionAuth type has been renamed to ConfiguredConnectionAuth.

  • breakingThe connection auth requirement

    Applies if you configure auth.

    Every connection must now configure at least one auth method. The none auth method is available for unauthenticated connections.

  • breakingThe AWS CodeCommit unauthenticated auth option, removed

    Applies if you configure the AWS CodeCommit unauthenticated auth option.

    The unsupported unauthenticated AWS CodeCommit auth option has been removed.

  • breakingThe repo schema openapi verify command rename

    Applies if you run repo schema openapi verify.

    The repo schema openapi verify command has been renamed to repo schema openapi validate.

  • breakingStricter --strict configuration checks

    Applies if you run --strict.

    The --strict flag for backstage-cli config:check and backstage-cli config:schema now treats TypeScript configuration schema errors as fatal.

  • breakingThe scaffolder template rendering native addon requirement, removed

    Applies if you run scaffolder template rendering.

    The native addon requirement has been removed from scaffolder template rendering.

  • breakingStricter OAuth URL allowlist validation

    Applies if you configure OAuth redirect URI allowlists, client ID metadata document allowlists, or redirect URIs.

    OAuth redirect URI and client ID metadata document allowlists now match patterns against each URL component separately. Wildcards no longer cross the host and path boundary, patterns must include an explicit protocol or they are rejected as invalid configuration, and redirect URIs with embedded credentials are always rejected.

  • breakingThe nodemailer TLS certificate default

    Applies if you use nodemailer and configure an SMTP relay or OAuth2 endpoint.

    nodemailer was updated from v8 to v9. The new major version validates TLS certificates by default when fetching remote content such as attachments or OAuth2 tokens, so email delivery may fail when the configured endpoint uses a self-signed or otherwise untrusted certificate; transport options can set tls: { rejectUnauthorized: false } to opt out.

  • breakingTypeScript scaffolder template rendering

    Applies if you run scaffolder template rendering.

    The native addon requirement has been removed from scaffolder template rendering. Templates now run through a TypeScript interpreter, and the backend no longer needs the --no-node-snapshot Node.js option.

Plan ahead (2)

  • deprecatedZod v3 schema support, deprecated

    Applies if you use Zod v3.

    Zod v3 schemas remain supported but are deprecated.

  • deprecatedDynamic plugin discovery for the internal OpenAPI documentation provider

    Applies if the internal OpenAPI documentation provider runs and you do not configure catalog.providers.backstageOpenapi.plugins.

    The internal OpenAPI documentation provider now discovers installed plugins through the system metadata service. The catalog.providers.backstageOpenapi.plugins option is optional and deprecated; when omitted, all installed plugins are discovered dynamically.

All 183 other recorded changesvalue changes 71 · additions 54 · fixes 47 · constraints 8 · defaults 3

value changes (71)

  • chore(deps): bump dompurify from 3.4.11 to 3.4.12
  • Hardened backend startup against malformed installed backend features, with contextual input errors and configured boot-failure handling when invalid registrations can be attributed to a plugin or module.
  • chore(deps): bump shell-quote from 1.8.4 to 1.9.0
  • The --strict flag for config:check now treats TypeScript configuration schema errors as fatal.
  • The Kubernetes API proxy now refreshes cached middleware when cluster details change, after a configurable TTL, or when the cache reaches its size limit.×2
  • Improves scaffolder entity pickers by using the catalog POST endpoint so large template filters are sent in the request body instead of the URL, helping avoid 431 errors and empty option lists.
  • - 78bf918: chore(deps): bump tar from 7.5.15 to 7.5.21
  • - 226817d: chore(deps): bump js-yaml from 4.2.0 to 4.3.0
  • Updated GitHub authentication selection to prefer an organization-specific App, then an unrestricted App, and finally the only configured App before falling back to token or anonymous authentication.
  • The Catalog backend now syncs entity relations by applying only the diff of changed rows instead of deleting and reinserting all relations.
  • Migrated the Unprocessed Entities UI to Backstage UI components and added search to the pending entities tab.
  • Scaffolder tasks now wait for recovery checkpoint state to be persisted before continuing, and restored checkpoints preserve falsy values without re-running their callbacks.
  • Updated generated plugin templates to use toastApiRef, add UserInfoService to permission policy modules, and include better table accessibility and backend module dependencies.
  • Improved TypeScript 7 forward-compatibility in Catalog exports and the Backstage ESLint plugin.
  • Updated nodemailer from v8 to v9 in the email notifications module.
  • This significantly reduces API usage against the 15k/hour GitHub App rate limit for organizations with many installations or frequent credential refreshes.
  • Skip SSRF protection for CIMD metadata fetches when the client_id matches an exact (non-wildcard) entry in allowedClientIdPatterns. Exact patterns mean the administrator explicitly listed a specific URL, so the DNS resolution is trusted. Wildcard patterns still enforce the SSRF check to protect against attacker-controlled subdomains resolving to internal addresses.
  • Replaced the delete-all and reinsert pattern for the relations table with a diff-based sync that only touches rows that actually changed. In steady state (the common case), zero writes occur, eliminating write churn, dead tuples, and WAL traffic from the processing path.
  • TypeScript configuration schema warnings discovered while setting up secret redaction are now reported through the Backstage logger.
  • Package preparation for publishing validates TypeScript configuration schemas strictly, preventing invalid schemas from being published. Other build and bundle paths report schema errors as warnings.
  • Updated the plugin-web-library template to use toastApiRef from @backstage/frontend-plugin-api instead of the deprecated alertApiRef from @backstage/core-plugin-api.
  • 226817d: chore(deps): bump js-yaml from 4.2.0 to 4.3.0×2
  • 9fcfbc9: Fixed a performance issue where all components using analytics, including every link, would rerender unnecessarily whenever a surrounding analytics context rendered again without its attributes having changed, for example when a URL query parameter changed on an entity page.
  • 6497d0f: Respect explicit API reference plugin ownership when resolving conflicting API factories.
  • Updated dependencies - @backstage/[email protected] - @backstage/[email protected]×13
  • Updated dependencies - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected]×3
  • Updated dependencies - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected]
  • Updated dependencies - @backstage/[email protected] - @backstage/[email protected]
  • Updated dependencies - @backstage/[email protected] - @backstage/[email protected]
  • Updated dependencies - @backstage/[email protected]
  • Updated dependencies - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected]
  • Updated dependencies - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected]
  • Updated dependencies - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected]
  • Updated dependencies - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected]×2
  • Updated dependencies - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected]×4
  • Updated dependencies - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected]×2
  • Updated dependencies - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected]
  • Updated dependencies - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected]
  • Updated dependencies - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected]
  • Updated dependencies - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected]
  • Updated dependencies - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected]
  • Updated dependencies - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected]
  • Updated dependencies - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected]
  • Updated dependencies - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected] - @backstage/[email protected]
  • The owner list is now virtualized, keeping the picker responsive for catalogs with large numbers of owner entities.
  • Migrated the Unprocessed Entities UI to the Backstage UI component library. The page, dialogs, and action buttons now use the new design system, and the raw entity definition and delete confirmation dialogs have an updated look and feel.
  • fa72461: Updated dependency @opentelemetry/core to ^2.0.0.
  • 9da01b6: chore(deps): bump http-proxy-middleware from 3.0.5 to 3.0.7
  • Invalid cache configuration values fall back to defaults.
  • Added scopes_supported to the OAuth 2.0 Protected Resource Metadata (RFC 9728) response. Without this field, RFC-compliant MCP clients did not know which scope to request and never received a refresh token, causing sessions to expire with the short-lived access token. The field now includes openid, and also offline_access when auth.experimentalRefreshToken is enabled.

additions (54)

  • Added coreServices.rootSystemMetadata, a new stable public service for reading metadata about the running Backstage system, including a list of installed plugins.
  • Added optional allowedTools, license, and compatibility fields to the @alpha AiResource skill spec
  • Added buildConnectionsFromConfig, which reads legacy integrations configuration together with connections configuration and returns the fully validated and merged list of connections.
  • Added support for creating a GitHub credentials provider backed by the connections service.
  • Add initialFilter config for page:techdocs. Valid options are all, owned and starred. Defaults to owned.
  • The same flag is now also available for config:schema.
  • Added an onSchemaError callback that allows callers to report TypeScript configuration schema errors and continue loading.
  • Added support for configuring MCP server instructions for both default and named servers.
  • Added support for routing notifications to a specific Slack channel via payload.metadata.slackChannel, with the existing entity annotation lookup as a fallback.
  • - a178067: Added a Home page search bar widget blueprint for the new frontend system.
  • Added a new aws connection type for AWS account credentials, looked up by AWS account number or ARN rather than by URL.
  • Added a new package schema openapi validate command to validate that an OpenAPI spec is a valid OpenAPI 3.x document.
  • New apps created with @backstage/create-app now include a GitHub Actions CI workflow that runs linting, type checking, tests, configuration validation, and a Docker image build on pull requests.
  • The app template also includes a pre-configured Home page with a customizable widget grid
  • The Home plugin now includes new frontend system widget blueprints for Most Visited, Recently Visited, World Clocks, a configurable Toolkit, and a search bar from the Search plugin.
  • The home page layout now supports a defaultConfig for defining the initial widget grid through app configuration.
  • now includes a refresh-catalog-entity action that agents and MCP clients can use to re-queue a single entity for processing
  • @backstage/plugin-kubernetes-backend now emits auditor events for cluster list, cluster proxy, entity workload, custom resource, and deprecated services endpoint requests.
  • @backstage/plugin-mcp-actions-backend now emits audit events for MCP server connection, tool discovery, and tool execution operations.
  • MCP servers can also be configured with instructions for both default and named servers.
  • The TechDocs page extension now accepts an initialFilter configuration value for page:techdocs.
  • @backstage/config-loader also adds an onSchemaError callback that callers can use to report schema errors and continue loading.
  • Added support for using a SubRouteRef as the parent of another SubRouteRef in the new frontend system.
  • Allowed ChatGPT Codex clients to use Client ID Metadata Documents by default.
  • Added support for routing Slack notifications to a specific channel via payload.metadata.slackChannel.
  • Added a kubernetes.clusterLocatorContinueOnError configuration option so a failing cluster locator can be skipped while clusters from other locators are still returned.
  • Added new backstage-cli new templates for permission policy modules, search collator modules, and catalog processor modules.
  • Added marketplace spec type to the @alpha AiResource kind
  • Added plugin spec type to the @alpha AiResource kind
  • Added support for using a SubRouteRef as the parent of another SubRouteRef.
  • Added a refresh-catalog-entity action so agents and MCP clients can re-queue a single entity for processing after creating or updating it
  • Added a new public @backstage/backend-defaults/rootSystemMetadata entrypoint, exporting rootSystemMetadataServiceFactory and DefaultRootSystemMetadataService.
  • Added a new permission-policy-module template for scaffolding custom permission policies via backstage-cli new.
  • Added a search-collator-module template for scaffolding new search collator modules via backstage-cli new.
  • Added a new catalog-processor-module template for scaffolding catalog processor modules via backstage-cli new.
  • Added UserInfoService to the permission-policy-module template so that scaffolded permission policies have the service already wired up for ownership lookups.
  • 9138f34: Added a GitHub Actions CI workflow to the default app template. New Backstage instances created with create-app now include a .github/workflows/ci.yml that runs lint, type checking, tests, configuration validation, and a Docker image build on every pull request.
  • a178067: Added a pre-configured Home page with a customizable widget grid to the default create-app template.
  • 2828e31: Added a prerequisites check when creating a new app that validates Node.js LTS version and Yarn availability before proceeding, and warns if Python is not found.
  • 4ce59cc: Added an alpha createAwsCredentialsManagerFromConnection export that creates an AwsCredentialsManager backed by the connections system, allowing AWS credential resolution through the new aws connection type. The existing configuration-based setup is unchanged.
  • The pending entities tab now also has a search box, matching the failed entities tab.
  • a178067: Added new frontend system widget blueprints for Most Visited, Recently Visited, World Clocks, and a configurable Toolkit.
  • a178067: Added HomePageDefaultConfigItem type and optional defaultConfig prop to HomePageLayoutProps.
  • c6af8ac: Added audit logging for kubernetes-backend routes. The plugin now emits auditor events for cluster list, cluster proxy, entity workload queries, custom resource queries, and the deprecated services endpoint. Administrators can filter audit logs by eventId values cluster-fetch and resource-fetch, and by queryType in event metadata.
  • KubernetesProxyOptions accepts an optional auditor for adopters that construct the proxy directly.
  • At startup, the backend logs a warning for each cluster configured with skipTLSVerify: true.
  • Optional configuration is available under kubernetes.proxy.middlewareCache.
  • f0834bd: Added a kubernetes.clusterLocatorContinueOnError configuration option.
  • Added audit logging for MCP server operations using the Backstage Auditor Service. The plugin now emits connection, tool-discovery, and tool-execution audit events, allowing adopters to monitor and audit MCP server activity.
  • Added a new aws connection type for AWS account credentials, looked up by AWS account number or ARN rather than by URL. A single account auth method covers all accounts: one entry per account with static keys, a profile, or IAM role assumption, and at most one entry marked mainAccount: true that acts as the fallback for the environment's own account. A connection-level roleName (with optional partition, region, externalId, and webIdentityTokenFile) describes a role to assume in any account that has no entry of its own.
  • legacy top-level aws configuration is converted automatically, with explicit connections config taking precedence
  • Connection types can now declare a whole-connection validation step that runs after the configuration schemas have parsed, enabling rules that span multiple auth entries or combine connection settings with auth entries.
  • Each auth entry includes its plugin match, allowing rules to take plugin scoping into account.
  • Connection types also expose a type-level auth accessor describing the shape of their configured auth entries, mirroring the existing query accessor.

fixes (47)

  • Corrected catalog relation generation to honor declared kind combinations, and completed reverse relations for existing AiResource fields.
  • Fixed the built-in CLI client being rejected when allowedClientIdPatterns is configured for Client ID Metadata Documents.×2
  • Fixed a missing promise return in a database migration rollback function.
  • Fixed a bug in the Azure DevOps URL reader where the abort signal was not forwarded to the commits API fetch, causing the fetch to hang indefinitely when a build timeout or cancellation was triggered.
  • Fixed yarn new failing with "No version available" for several templates by adding missing packages to the version map.
  • Fixed generated frontend plugin tables to identify their row header
  • Fix issue where backstage-cli config:check --strict would incorrectly reject valid configuration for open-ended object schemas, such as plain objects or map-like structures.
  • 7ca2955: Fix OAuth start handler crashing with a 500 error on malformed origins, now returns a 400 error.
  • 05aed2e: Fixed a brief "Entity not found" flash when navigating between catalog entity pages.
  • Fixed notification recipient resolution to safely handle cyclic group relationships during group traversal, preventing endless recursion.
  • Fixed the stale task janitor not being set up by passing the scheduler service to the router.
  • Scaffolder tasks now wait for recovery checkpoint state to be persisted before continuing, preventing later execution from racing ahead of stored recovery state.
  • Entity provider mutations on PostgreSQL now retry automatically on deadlocks
  • SCM location.moved events are also ignored for files that are not actively tracked, preventing spurious locations from being created.
  • A bug where strict config checks incorrectly rejected valid open-ended object schemas has been fixed.
  • Fixed Table not filling the container width in Firefox when TableRoot is used directly inside ResizableTableContainer.
  • Fixed config-driven route redirects in the new frontend system so they preserve the query string and fragment from the original URL.
  • Fixed unnecessary entity page and analytics rerenders when surrounding context values had not changed.
  • Fixed a brief "Entity not found" flash when navigating between catalog entity pages.
  • Fixed the catalog graph page so configured filter and graph defaults are applied when the page opens.
  • Fixed the DependencyGraph component so nodes no longer briefly overlap before the initial layout settles.
  • Fixed UserListPicker showing all catalog entities as "Owned" when the logged-in user has no ownership entity refs.
  • Fixed OAuth start requests with malformed origins returning a 500 instead of a 400.
  • Fixed Microsoft provider sign-in and token refresh for non-Graph scopes, such as Azure Management API scopes.
  • Fixed MCP OAuth metadata so RFC-compliant clients know which scopes to request and can receive refresh tokens when refresh tokens are enabled.
  • Fixed limited user token creation so it throws when required user IP metadata is missing instead of constructing an invalid token.
  • Fixed backstage-cli new failing with "No version available" for several templates.
  • Fixed an issue where PostgreSQL deadlock errors during entity provider mutations were silently swallowed, causing entities to be dropped until the next full refresh. Transactions are now automatically retried on deadlock with exponential back-off.
  • Fixed a potential MySQL deadlock during concurrent entity processing by retrying the updateProcessedEntity transaction on deadlock errors.
  • Fixed an issue where SCM location.moved events would generate new locations in the database for files that were not actively tracked.
  • Throw an error when payload.uip is missing in createLimitedUserToken instead of constructing an invalid limited token with an undefined signature.
  • Identity mocks passed to renderInTestApp (for example via mockApis.identity(...)) are now applied before the app's built-in guest fallback, so the configured userEntityRef reliably takes effect in tests instead of being silently overwritten by the default guest user.
  • Fixed the DependencyGraph component to avoid a jarring initial render where nodes briefly pile up at overlapping positions before animating into place. The graph content is now hidden until node measurements are complete and the layout has fully settled, then revealed at the correct positions with transitions suppressed for the first frame. Also fixed a containerRef recreation chain where every graph dimension change caused the container measurement callback to be recreated and re-triggered, producing unnecessary re-renders during initial layout.
  • ee4a9f6: Fixed the example scaffolder template so the component name field validates against the allowed entity-name format, preventing names with spaces that would fail catalog registration.
  • 52a58be: Fixed Table not filling container width in Firefox when using TableRoot directly inside ResizableTableContainer. Changed overflow: hidden to overflow: auto on the resizable container so it handles scrolling for direct TableRoot usages.
  • b7085d1: Fixed deep linking in OpenAPI definition widget.
  • 2dd51e6: Fixed config-driven route redirects to preserve the query string and fragment from the original URL. Previously, redirects declared under app.extensions[].app/routes.config.redirects silently dropped everything after ? or # in the incoming URL.
  • 7ccaf9d: Fixed an issue where acquiring tokens with non-Graph scopes (such as Azure Management API) would crash the sign-in resolver because the user profile was unavailable. This affected both the initial sign-in and later token refreshes. The Microsoft authenticator now makes a separate Graph API call to fetch the profile when the primary token targets a different resource. Setting the skipUserProfile configuration option to true disables this extra call.
  • 80b37b3: Fixed the AboutField label in the About card using variant="inherit" instead of variant="h2" to prevent theme typography overrides from changing the intended 10px label size.
  • 8babce3: Fixed the catalog graph page so configured filter and graph defaults are applied when the page opens.
  • Remove obsolete location import error handling in StepReviewLocation.
  • Fixed a performance issue where all components reading the entity context on an entity page would rerender unnecessarily whenever the page rendered again without the entity data having changed, for example when a URL query parameter changed. This was particularly noticeable when switching tabs in the entity inspector dialog, which caused the entire underlying page to rerender.
  • Fixed an issue where the "Owned" count in UserListPicker would display the total number of catalog entities instead of 0 when the logged-in user has no ownership entity refs. The empty relations.ownedBy filter was being silently dropped by the catalog client, causing the backend to return all entities with no ownership filter applied.
  • Fixed EntityOwnerPicker in owners-only mode to display human-readable entity titles (from metadata.title or spec.profile.displayName) instead of opaque internal names, both in the dropdown list and in the selected owner chips.
  • 684c9b9: Fixed AwsIamStrategy to resolve account-specific AWS credentials when an assume role ARN is configured, enabling support for webIdentityTokenFile and accountDefaults in environments without default AWS credentials.
  • Restored checkpoints also preserve falsy values without re-running their callbacks.

constraints (8)

  • Permission rule parameter schemas now accept JSON Schema-compatible Standard Schema implementations, such as Zod v4.×2
  • Configurations with duplicate account IDs or multiple main account entries are rejected at startup×2
  • Changed connection types to use portable configuration schemas as the source of root connection types, with JSON Schema generation and strongly typed parsing that do not expose the underlying Zod schemas.
  • Package preparation now validates TypeScript configuration schemas strictly before publishing.
  • Made the description parameter optional in the publish:gerrit scaffolder action.
  • - f83a652: Made description parameter optional in publish:gerrit action.

defaults (3)

  • Allow ChatGPT Codex clients to use Client ID Metadata Documents by default.
  • The system metadata service is now registered automatically as a default service, so backends no longer need to add it manually.
  • 943687f: Generated backend Dockerfiles no longer disable the Node.js snapshot or install native build dependencies for the Scaffolder.
Add Backstage to your stack

A weekly email arrives when a release needs action. Like the breaking changes in this release.

Add to stack →
Official release note ↗All Backstage releases →