RATATOSKRATATOSK
Sign in

Backstage

v1.56.0CI/CD & App Delivery
Oct 20, 2026

ACTION 1CHECK 14PLAN 7OTHER 256

A feature-rich platform release adds backend, CLI, TechDocs, catalog, search, and plugin capabilities. It also includes breaking API, database, authentication, configuration, and default-behavior changes, plus reliability, performance, correctness, dependency, and security updates that may require targeted migration and validation.

Action needed (1)

  • securitynodemailer version 10

    nodemailer was updated to version 10 to address security vulnerabilities in older releases.

Check if affected (14)

  • breakingObject-only FilterPredicate roots

    Applies if you use FilterPredicate.

    FilterPredicate now accepts only objects at the root of a predicate. This constraint is enforced by parseFilterPredicate.

  • breakingRemoval of usernameMatchingUserEntityName

    Applies if you use the usernameMatchingUserEntityName sign-in resolver.

    The usernameMatchingUserEntityName sign-in resolver has been removed. The change also affects sign-in configurations that used this resolver.

  • breakingRequired service instance ID

    Applies if you use custom implementations or mocks of the service.

    Custom implementations and mocks of the service must now provide an instance ID. The identifier is represented by instanceId.

  • breakingNon-rolling ingestion_mark_entities migration

    Applies if you perform a rolling, zero-downtime upgrade.

    The migration cannot be applied as part of a rolling, zero-downtime upgrade. It affects the ingestion_mark_entities migration and its source_key and entity_ref data.

  • breakingBackstage 1.49 catalog backend requirement

    Applies if you use a catalog backend from Backstage release 1.49 or later.

    This change requires a catalog backend from Backstage release 1.49 or later.

  • breakingStartup rejection of non-positive stitching intervals and lease durations

    Applies if you configure stitching polling intervals or lease durations.

    Non-positive stitching polling intervals and lease durations are rejected at startup.

  • breakingUser identity token requirement for the signals WebSocket endpoint

    Applies if you expose the signals WebSocket endpoint.

    The signals WebSocket endpoint now requires a valid user identity token.

  • breakingStable unique ID for the root instance metadata service

    Applies if you use custom implementations or mocks of the root instance metadata service.

    Custom implementations and mocks of the root instance metadata service must now provide a globally unique ID that remains stable for the lifetime of the running backend instance.

  • breakingRemoval of disabledKeys from MenuSection

    Applies if you use MenuSection with disabledKeys.

    MenuSection no longer accepts disabledKeys.

  • breakingRemoval of usernameMatchingUserEntityName

    Applies if you use the usernameMatchingUserEntityName sign-in resolver.

    The usernameMatchingUserEntityName sign-in resolver has been removed. Sign-in configurations using this resolver are affected.

  • breakingThe table ref column renamed to entity_ref

    Applies if you use the table's ref column.

    The table's ref column has been renamed to entity_ref.

  • breakingDisabled database keepalive queries by default

    Applies unless you set backend.database.keepalive to true.

    Periodic per-plugin database keepalive queries are no longer issued by default, and the default minimum PostgreSQL and MySQL connection pool size is now zero. Idle connections can be retired after the configured timeout, while explicitly configured pool minimums are preserved. Set backend.database.keepalive to true to continue issuing the periodic queries.

  • breakingStartup rejection of non-positive stitching intervals and lease durations

    Applies if you configure stitching polling intervals or lease durations.

    Non-positive stitching polling intervals and lease durations are rejected at startup.

  • breakingUser identity token requirement for the signals WebSocket endpoint

    Applies if you expose the signals WebSocket endpoint.

    The signals WebSocket endpoint now requires a valid user identity token. The token can appear anywhere in the requested WebSocket protocols. Connections without a token, with an invalid token, or with a non-user service token are rejected, and unauthenticated guest connections are no longer accepted.

Plan ahead (7)

  • deprecatedDeprecated getCatalogFilters

    Applies if you use getCatalogFilters.

    getCatalogFilters is deprecated. Existing uses of this API are affected by the deprecation.

  • deprecatedDeprecation warnings for serve:mkdocs and --mkdocs-parameter-*

    Applies if you use serve:mkdocs or the --mkdocs-parameter-* flags.

    The serve:mkdocs command and --mkdocs-parameter-* flags now print deprecation warnings.

  • deprecatedDeprecated raw token outputs without variableKey

    Applies if you use raw token outputs and do not configure variableKey.

    Raw token outputs are deprecated when variableKey is not used.

  • deprecatedDeprecated totalItems option

    Applies if you configure totalItems.

    The totalItems option is deprecated.

  • deprecatedDeprecation warnings for serve:mkdocs and --mkdocs-parameter-*

    Applies if you use serve:mkdocs or the --mkdocs-parameter-* flags.

    The serve:mkdocs command and --mkdocs-parameter-* flags now print deprecation warnings.

  • deprecatedDeprecated and ignored StreamEntitiesRequest.totalItems

    Applies if you use totalItems.

    The totalItems option of StreamEntitiesRequest is deprecated and ignored.

  • deprecatedDeprecated raw token outputs without variableKey

    Applies if you use raw token outputs and do not configure variableKey.

    Raw token outputs are deprecated when variableKey is not used.

All 256 other recorded changesvalue changes 131 · fixes 64 · additions 43 · constraints 11 · renames 4 · defaults 3

value changes (131)

fixes (64)

  • Successfully processed entities no longer remain unavailable if stitch scheduling is interrupted
  • Entities no longer disappear from filtered and sorted catalog queries after a database error during stitching
  • Combobox keyboard selection while filtering has been fixed
  • useRouteRef now resolves routes again after finalization
  • Fixed the catalog entity list rewriting the URL on every render
  • Fixed catalog processing error messages to report stable processor names in minified builds.×2
  • Fixed the Gitea entity provider registering locations against a hardcoded main branch
  • Reading a number from an empty or whitespace-only config value now fails with a clear error instead of returning 0.
  • fixed AWS RDS IAM authentication tokens being reused after their signing credentials expire
  • Fixed serializeError to strip stack traces from all nested error causes.
  • The selected sign-in provider is no longer cleared when a sign-in loader is cancelled.
  • Fixed protected app sign-in returning a 404 when the sign-in handoff is repeated.
  • Fixed long words in toast notifications overlapping the close button.
  • Fixed Azure DevOps downloads to use the requested branch or tag.
  • Fixed importing @backstage/integration from ESM projects.
  • now throws a clear ConflictError when the target repository already exists.
  • Fixed a regression where scaffolder step values consisting of a single template statement block, such as if conditions, were rendered as strings instead of booleans.
  • Fixed Elasticsearch search queries intermittently failing when a collator finishes indexing.
  • Fixed PostgreSQL search highlighting with delimiters that need quoting.
  • Fixed TechDocs asset caching on reused HTTP connections.
  • Fixed TechDocs rejecting mkdocs.yml files that use Material for MkDocs emoji and superfences configuration
  • Fixed the no-mixed-plugin-imports lint rule silently reporting nothing
  • Fixed root setupFilesAfterEnv Jest configuration being shared between workspace packages
  • Fixed Combobox keyboard selection while filtering.
  • Fixed the catalog entity list re-writing the URL on every render
  • Fixed TechDocs addons silently not rendering in apps using the new frontend system
  • Fixed TechDocs asset caching on reused HTTP connections to avoid listener leaks and cross-request response corruption.
  • Fixed TechDocs allowing custom_icons paths in mkdocs.yml that resolve outside the documentation input directory.
  • Fixed TechDocs generation rejecting mkdocs.yml files that use the emoji indexes and generators or the pymdownx.superfences custom fence formats
  • Fixed Material UI styles for TechDocs addons in module-federated applications.
  • a lazy addon no longer hides the surrounding reader while it loads.
  • Prevented TechDocs content from briefly appearing before page styles load.
  • Fixed AWS RDS IAM authentication tokens being reused after their signing credentials expire, which could cause database connection failures when using temporary AWS credentials.
  • Fixed the conversion of legacy filters that happens when a request has both a filter and a query, so that it matches the semantics of the legacy filter query parameter. Empty filters no longer turn into a predicate that matches nothing, empty records no longer match everything, and string values take precedence over CATALOG_FILTER_EXISTS for the same key.
  • Fixed backstage-cli pm verify-patches failing to load unless projects installed the Yarn CLI package separately.
  • jest-cli, jest-runtime and the default Node.js test environment are now loaded through the installed jest package, so tests also run with strict node_modules layouts. An unsupported Jest version, or a missing jest, now fails with a clear error instead of a module resolution error.
  • Fixed setupFilesAfterEnv from the root package.json Jest configuration being shared between workspace packages, which caused each package's src/setupTests file to also be added to every other package.
  • Fixed CommonJS frontend test execution with ESM dependencies on Node.js 24.
  • Commands run through runCli now wait for stdout and stderr to be flushed before exiting, so large command output is no longer truncated on platforms where writes to stdout and stderr are asynchronous.
  • Fixed CLIs created with runCli silently exiting when the root or a command group is invoked without a subcommand. They now display help for that level and complete successfully.
  • Reading a number from a configuration value that is an empty or whitespace-only string now fails with a clear conversion error, instead of silently returning 0. Numeric strings, including ones with surrounding whitespace such as ' 42 ', continue to be parsed as expected.
  • Fixed the Connection type so that auth is a union of method variants instead of an array when no specific auth method is provided.
  • Declared the dependencies of internally bundled code so that the package works with strict node_modules layouts.
  • Stop clearing the selected provider from localStorage when a sign-in loader is cancelled. Only clear it when the loader actually fails.
  • Fixed default landing page configuration in the app template so the Home page path override is inside the existing page:home block.
  • Fixed serializeError so that stack traces are stripped from all nested error causes when stacks are not requested, not just the first-level cause.
  • Fixed Azure DevOps file and archive downloads to use the requested branch or tag, including when checking whether a repository tree has changed. Branches and tags with the same name are now distinguished.
  • Bitbucket Cloud OAuth access tokens returned by getBitbucketCloudOAuthToken are now cached separately for each set of OAuth client credentials. Previously a single token was cached globally, which could cause the wrong token to be used when more than one Bitbucket Cloud integration was configured or when OAuth credentials were rotated.
  • Fixed importing this package from ECMAScript module (ESM) projects, which failed since 2.1.0 with an error saying that lodash does not provide an export named trimEnd.
  • Fixed CLI report generation failing when the FORCE_COLOR environment variable is set.
  • Declared the dependencies of internally bundled code so that the package works with strict node_modules layouts
  • Fixed long words in toast titles and descriptions overflowing the notification and overlapping the close button.
  • - c55505e: Fix protected app sign-in returning a 404 when an authenticated browser repeats the sign-in handoff for the same user.
  • Fixed an issue where successfully processed entities could remain unavailable if stitch scheduling was interrupted.
  • Entity and location queries with a primitive value at the root of the filter predicate are now rejected with an "Invalid query" error, rather than "Query must be an object".
  • Pending stitching work is no longer lost when entities are deleted and re-added
  • Fixed entities disappearing from filtered and sorted catalog queries after a database error during stitching.
  • PostgreSQL and MySQL deadlocks trigger prompt, bounded retries of the entire write transaction
  • - f181c5f: Fixed the Gitea entity provider registering catalog-info.yaml locations against a hardcoded 'main' branch instead of each repository's actual default branch.
  • - 6e08d65: Fixes a regression where scaffolder step values consisting of a singular template statement block (ex. if: "{% if parameters.foo == 'bar' %}true{% else %}false{% endif %}"), were rendered as the strings "true" and "false" instead of their boolean values. This caused steps with if conditions to always run. Step values with a single statement block that renders nothing, such as {% if false %}x{% endif %}, are once again left out of the action input instead of being passed as an empty string.
  • - 06128be: Throw a ConflictError with a clear message when publish:gitlab is called and the target repository already exists, instead of letting the GitLab API return a GitbeakerRequestError with a raw JSON body such as {"name":["has already been taken"]}.
  • - 2153e90: Fixed search queries intermittently failing with a 500 error when a collator finished indexing. The index that the search alias pointed to before the rotation is no longer deleted immediately, so queries already running against it can complete. It is instead removed during the next indexing run for that document type. Note that this means the previous index is now retained between runs, so search storage usage per document type is roughly doubled. Also improved error reporting for failed search queries. An index that disappears while a query is running is now reported as a missing index, and other query failures now include the underlying cause in the logs instead of undefined.
  • - 7535616: Fixed PostgreSQL search highlighting when configured delimiters or selection tags contain punctuation that requires quoting.

additions (43)

  • has a new getCatalogQuery method
  • Three new CLI modules provide domain-oriented commands that talk directly to the corresponding plugin APIs
  • @backstage/cli-module-catalog: catalog list, catalog get, catalog validate, catalog register, catalog unregister
  • @backstage/cli-module-scaffolder: template list, template execute, template dry-run
  • @backstage/cli-module-search: search, docs search
  • This introduces an --engine flag in the TechDocs CLI, an engine configuration map, a generator registry
  • A new withoutFeedbackLink option
  • registers a get-techdocs-metadata action
  • Backends created with createBackend now provide the experimental connections service by default.
  • provides a Featured Templates home page widget
  • a swappable UserAvatar component
  • have a new variableKey input
  • A new theme CSS cascade layer
  • Added AppLifecycleApi
  • Added a backend.logger.redactAllowlist configuration option
  • Added bounded retries for transient Cloud SQL connection failures
  • Added a service-authenticated action registry status endpoint
  • Added a defaultCloseDelayMs option to SubmenuOptions.
  • Added a --fix mode to backstage-cli pm verify-patches.
  • Added an instanceId option to createSpecializedBackend.
  • Added experimental declareConnection and connectionsServiceRef exports
  • Add intent-based CLI modules for catalog, scaffolder, and search.×2
  • A new AnyFilterPredicate type describes predicates that may also be primitive values at the root
  • Introduces --engine flag, engine config map, generator registry with backstage.io/techdocs-engine annotation support, engine field in techdocs_metadata.json, serve:raw command, and live-reload adapter interface.
  • Added a theme CSS cascade layer between components and utilities.
  • Added a source_key column and a UNIQUE(source_key, entity_ref) constraint
  • Added getCatalogQuery to EntityFilter
  • Added a swappable UserAvatar component
  • Added a Featured Templates homepage widget
  • Added withoutFeedbackLink prop to page:techdocs/reader and entity-content:techdocs extensions
  • Added a get-techdocs-metadata action to the TechDocs backend plugin
  • Added a service-authenticated action registry status endpoint that reports whether a plugin provides actions without exposing action metadata.
  • Added an instanceId option to createBackend, allowing deployments to use an externally provided backend instance identifier. Each backend instance uses a random UUID by default.
  • Added bounded retries for transient failures while initializing Cloud SQL database connections.
  • Added support for backend.logger.redactAllowlist configuration option, which allows specific secret values to pass through log redaction when they are known to be safe to log.
  • Added a conservative --fix mode to backstage-cli pm verify-patches that can update project-owned Backstage package patches when an automated release upgrade leaves them pinned to older versions. The repair requires Yarn 3 or later.
  • Added defaultCloseDelayMs option to SubmenuOptions to configure a delay before a submenu closes.
  • Provided an implementation of AppLifecycleApi and updated the app preparation and finalization process to utilize this API.
  • Added AppLifecycleApi and appLifecycleApiRef, which let you check whether the app has been finalized and subscribe to changes in its lifecycle.
  • - a18df8f: Added optional app.publicConfig allowlists for config key paths and extension IDs exposed to unauthenticated users of protected apps. Authenticated users retain access to all frontend-visible configuration, and existing behavior is unchanged unless filtering is enabled.
  • - fe51d40: Added a secure variableKey input to gitlab:projectAccessToken:create and gitlab:projectDeployToken:create actions. When provided, the generated token is stored directly as a masked GitLab CI/CD variable instead of being exposed in task outputs and checkpoint state.
  • - 45b0b89: Added a new techdocs.actions.read permission, available from the /alpha entry point, which controls access to the TechDocs actions registered with the Actions Registry.

constraints (11)

  • EntityTagFilter with multiple tags now requires all of them
  • Added Bitbucket Cloud support for bearer API tokens.
  • removed custom_icons paths that resolve outside the docs directory
  • Declared the per-cluster assumeRole and externalId options in the Kubernetes backend configuration schema.
  • now reports named imports from lodash, which break ESM builds.
  • Several packages now work with strict node_modules layouts.
  • The no-mixed-plugin-imports rule now also applies when the repository is checked out below a directory whose name starts with a dot, such as ~/.worktrees/my-repo.
  • Update Bitbucket Cloud Authentication logic to support bearer API token
  • CLI API reports now support help output with separate groups and commands sections, including commands nested within groups.
  • Updated SQL report generation to support newer Knex releases.
  • 0c9d72c: Update Bitbucket Cloud Authentication logic to support bearer API token

renames (4)

  • The built-in generator is now registered as mkdocs, with techdocs kept as an alias
  • Updated the plugin-web-library template to use @backstage/ui instead of the deprecated @material-ui/core.
  • - 66f8cf8: Replace deprecated createPermissionIntegrationRouter API call with permissionsRegistry
  • - 298f908: Replaced the unmaintained react-relative-time dependency with an internal component based on luxon.

defaults (3)

  • The backend no longer issues periodic per-plugin database keepalive queries by default, and the default minimum PostgreSQL and MySQL connection pool size is now zero.
  • The --bui-bg-app token now follows the page's color-scheme until a theme mode is set.
  • Backends created with createBackend now provide the experimental connections service by default. Custom backends can install connectionsServiceFactory from @backstage/backend-defaults/alpha.
Add Backstage to your stack

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

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