Skip to main content

v1.55.0

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

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

Highlights​

BREAKING: Removed deprecated catalog APIs and configuration​

This release removes several deprecated features from @backstage/plugin-catalog-backend.

The catalog.enableRelationsCompatibility config option and its associated compatibility layer have been removed. Entity relations are now always returned in the standard format with only targetRef. If you were relying on the target field in relations, update your code to use targetRef instead.

The deprecated CodeOwnersProcessor and AnnotateScmSlugEntityProcessor have been removed. Replace their custom registrations with the corresponding community modules: @backstage-community/plugin-catalog-backend-module-codeowners and @backstage-community/plugin-catalog-backend-module-annotate-scm-slug.

Remove the deprecated catalog.stitchingStrategy.mode key from your configuration. Stitching continues to run asynchronously, with pollingInterval and stitchTimeout still supported.

BREAKING: Elasticsearch 8 upgrade​

The @backstage/plugin-search-backend-module-elasticsearch package has upgraded its Elasticsearch client to version 8, requiring at least Elasticsearch 8.19 — the only 8.x release line still under support, following the end of life of Elasticsearch 7.x and earlier 8.x lines. Elasticsearch 7.x clusters are no longer supported.

If you use the elastic provider or connect to a plain Elasticsearch node, make sure your cluster is running Elasticsearch 8.19 or later before upgrading. The aws and opensearch providers keep using the OpenSearch client and are unaffected. Existing TLS settings continue to work without any configuration changes.

The methods of the ElasticSearchClientWrapper now return a normalized response that exposes body, statusCode, headers and warnings for both providers, instead of the client-specific response types. Code that relies on the raw client types or reads the meta property of a response needs to be adjusted.

Contributed by @axdotl in #34716

Backstage UI link components have been updated to use the hosting application's client-side router, including relative destinations and the application's configured router base path, while preserving native browser navigation where required. ListRow, Tag, and table Row now retain client-side navigation when application and plugin packages load separate React Aria copies.

Anchor-based components no longer accept the React Aria render prop. BUI now owns the underlying anchor so routing behavior remains consistent across application and plugin package versions. Remove render props from ButtonLink, ComboboxItem, Link, MenuItem, MenuListBoxItem, SearchAutocompleteItem, SelectItem, and Tab. BUI now selects and renders the appropriate anchor or router link automatically.

BREAKING: TechDocs MkDocs plugin allowlist​

TechDocs generation now removes MkDocs plugins outside the built-in allowlist and logs a warning before continuing the build. To retain additional plugins, review and add them to techdocs.generator.mkdocs.dangerouslyAllowAdditionalPlugins, or supply them through dangerouslyAllowAdditionalPlugins when creating the generator directly. Plugins configured through defaultPlugins are also permitted. Generation stops if the MkDocs configuration cannot be read, parsed, or updated.

BREAKING: Removed unused github:repo:create inputs​

Unused inputs have been removed from the github:repo:create action schema. The following inputs were previously accepted but silently ignored: blockCreations, branch, bypassPullRequestAllowances, defaultBranch, dismissStaleReviews, gitAuthorEmail, gitAuthorName, gitCommitMessage, protectDefaultBranch, protectEnforceAdmins, requireBranchesToBeUpToDate, requireCodeOwnerReviews, requiredApprovingReviewCount, requiredCommitSigning, requiredConversationResolution, requiredLinearHistory, requiredStatusCheckContexts, requireLastPushApproval, restrictions, and sourcePath. If your templates pass any of these to github:repo:create, remove them. Most of these inputs are supported by the github:repo:push action for branch protection, git authoring, and content publishing.

Contributed by @victoriacheng15 in #35571

BREAKING: Incremental ingestion permissions​

The incremental ingestion administrative routes in @backstage/plugin-catalog-backend-module-incremental-ingestion now enforce separate read and manage permissions. Installations with custom permission policies must add decisions for the new permissions.

BREAKING: Cloudflare Access provider requires audience​

The Cloudflare Access auth provider now requires the application audience in its configuration. Before upgrading, set auth.providers.cfaccess.audience to the Audience (AUD) tag shown for your Backstage application in Cloudflare Zero Trust.

BREAKING: Sentry scaffolder action URL restriction​

Sentry API requests in the scaffolder Sentry module are now restricted to the configured API base URL. Move custom action-level apiBaseUrl values to scaffolder.sentry.apiBaseUrl before upgrading.

Scaffolder task recovery​

A new scaffolder.taskRecovery config section enables automatic recovery of scaffolder tasks that crash or time out. When enabled, tasks resume from the last completed step, task secrets are retained until the task reaches a terminal state, and completed step outputs are persisted. Actions used by recovered tasks should be idempotent or use checkpoints.

Workspace serialization for task recovery now requires installing a separate workspace provider module. For development use the new @backstage/plugin-scaffolder-backend-module-workspace-database package (50 MB limit, not recommended for production). On first startup, it migrates existing database workspace snapshots from the legacy task storage. For production use @backstage/plugin-scaffolder-backend-module-gcp or a similar external storage provider. The scaffolder rejects a configured provider that has not been installed and registered.

The new config consolidates previous experimental flags (EXPERIMENTAL_recoverTasks, EXPERIMENTAL_workspaceSerialization, EXPERIMENTAL_recoverTasksTimeout) which remain supported as fallbacks.

Contributed by @dyatko in #35224

Scaffolder permissions and credentials​

A new scaffolder.requireScmUserCredentials configuration option requires user-provided credentials for supported SCM mutation and fetch actions. SCM provider modules for GitHub, GitLab, Bitbucket Cloud, Bitbucket Server, and Azure DevOps all support this setting.

The templateDryRunPermission is now applied to inline Software Template dry runs. Permission policies that deny unknown permissions must explicitly allow scaffolder.template.dry-run to retain existing dry-run access. New permissions for reading and managing catalog ingestion providers have been added to @backstage/plugin-catalog-common.

New package: @backstage/cli-module-package-manager-yarn​

A new CLI module that adds backstage-cli pm verify-patches to validate Yarn patch references, local patch files, lockfile consistency, and patched Backstage package versions against the selected Backstage release. The command is included in @backstage/cli-defaults. It also reports root-level Yarn resolutions that no longer match any dependency request in the lockfile.

Lazy frontend entry points and smaller bundles​

The initial app bundle size has been reduced across the board. Page and optional UI implementations for several core plugins — including catalog, home, search, TechDocs, user settings, DevTools, and catalog import — are now loaded only when their extensions render. The TechDocs LightBox addon's image viewer and the Kubernetes pod exec terminal (@xterm/xterm) are also lazily loaded. The Kubernetes entity content tab no longer loads its UI until the tab is opened.

The frontend bundle size is further reduced by letting bundlers tree-shake zod in @backstage/filter-predicates, which previously pulled every zod locale into the bundle. This takes effect on zod 4.5.0 and newer.

Contributed by @GabDug in #35287 and #35304

PostgreSQL improvements​

A new schemaPrefix configuration option for pluginDivisionMode: schema allows prefixing PostgreSQL schema names to avoid conflicts with existing schemas. Contributed by @Fortune-Ndlovu in #35603

PostgreSQL connection churn during backend startup has been reduced: startup connections are lowered when many plugins initialize databases or schemas, database existence checks are reused when multiple plugins share a database, and scheduler polling overhead is reduced by batching readiness checks into one query per poll cycle. Catalog query planning has been improved by correcting entity cardinality statistics and using stable array parameters for filter predicates and refresh state lookups.

TechDocs CLI improvements​

The techdocs-cli generate command now automatically computes a sha256 content hash of the generated site output and stores it as the etag in techdocs_metadata.json. A new --skip-if-unchanged flag on publish compares the local etag against the remote etag before uploading, skipping the publish step entirely when they match. This avoids redundant uploads in CI pipelines when docs haven't changed between builds. Contributed by @wscheep in #35227

A new --dangerouslyAllowAdditionalKeys option has been added to techdocs-cli generate. Contributed by @sid200727 in #35178

Support has also been added for techdocs.generator.pullOptions when pulling the TechDocs generator Docker image from private registries that require authentication. Contributed by @KarimSeoudy in #34277

Scaffolder template filtering and customization​

The sub-page:scaffolder/templates extension now accepts a templateFilter field that lets you filter which templates are shown on the template list page. Contributed by @dotboris in #34624

New ui:options have been added to RepoUrlPicker for per-template customization: ownerLabel, ownerDescription, repoLabel, repoDescription to override field labels, and disableRepoAutocomplete to render a plain text input instead of the autocomplete dropdown. Contributed by @savitojs in #34894

Support has been added for registering a Template Outputs Component in the new frontend system. Contributed by @jkomendant in #34419

Faster GitLab merge request and push actions​

The publish:gitlab:merge-request and gitlab:repo:push actions now make drastically fewer GitLab API requests. Under the default commitAction: 'auto', both actions previously downloaded the contents of every file already present on the target branch to determine which ones had changed. That comparison is now done locally using the repository listing they already fetch. For a merge request against a repository of a few hundred files this cuts the number of API requests from roughly 300 to under ten, reducing a step that took 5–15 seconds to about 3 seconds.

Contributed by @michael-todorovic in #35556

Kubernetes watcher interface​

A new KubernetesWatcher interface has been added for streaming Kubernetes resource changes via an async iterator. The watcher is separated from KubernetesFetcher because watching is a long-lived streaming connection that only works with server-side auth providers. Watch supports all event types (ADDED, MODIFIED, DELETED, BOOKMARK, ERROR) with errors yielded as data rather than thrown.

Contributed by @gabemontero in #34294

Deprecated GitHub username sign-in resolver​

The GitHub username sign-in resolver in @backstage/plugin-auth-backend-module-github-provider has been deprecated in favor of the stable user ID resolver. GitHub user ID catalog lookups now require an exact match and handle candidates that differ only by letter casing.

Backstage UI updates​

Several improvements to Backstage UI components including fixed pagination state handling in useTable, Combobox opening suggestions on focus, FullPage scrollable layout fix with PluginHeader, TablePagination synchronization fixes, and locale-insensitive string handling across the framework.

Fixed an issue where using PluginHeader with FullPage caused the page to be unexpectedly scrollable. Contributed by @varshini03 in #35183.

Check the BUI Changelog for more details.

Additional fixes and improvements​

  • The FixDialog, ContainerCard, and PodLogs components in @backstage/plugin-kubernetes-react no longer accept an implicit children prop, aligning with ADR006. Contributed by @suletetes in #35154.
  • Fixed the owner selected in the catalog import stepper being written to the generated catalog-info.yaml as a display name instead of an entity reference. Contributed by @MFA-G in #35235.
  • Fixed EntityOwnerPicker crashing with missing or empty kind errors when the owners query parameter contains humanized entity refs. Contributed by @mythrilium in #35270.
  • Fixed CopyTextButton showing its tooltip on hover/focus instead of only after clicking. Contributed by @reachsanjivbhagat-gif in #34920.
  • Added an optional variant prop to CopyTextButton for configuring its visual style. Contributed by @victoriacheng15 in #35567.
  • Added an onCopyLog prop to the LogViewer component that renders a copy button in the toolbar. Contributed by @tobiasp284 in #35006.
  • Added support for rendering custom link elements inside HeaderIconLinkRow.
  • Fixed app.extensions shorthand and disabled field to accept boolean-ish strings so environment variable substitution can toggle extensions. Contributed by @tanaysingh2512 in #35261.
  • Fixed a bug where overriding a plugin extension with withOverrides moved the overridden extension to the end of the plugin's extension list. Contributed by @gustavolira in #35613.
  • Fixed a bug where plugin packages installed through feature discovery were loaded before the app's own code ran. Contributed by @kuangp in #35053.
  • The default MCP server at /api/mcp-actions/v1 is now always exposed even when named servers are configured. Contributed by @majdsalman2 in #35383.
  • Added an unread notifications home page card and new frontend system home widget. Contributed by @ciiay in #34869.
  • The gitlab:issues:create action now accepts a full project path for projectId, and projectId is optional. Contributed by @kersten in #34544.
  • Added an autoMerge boolean input to publish:gitlab:merge-request. Contributed by @PG2000 in #34947.
  • Fixed gitlab:repo:push failing with a 400 error when the workspace has no file changes to commit. Contributed by @Naga15 in #34480.
  • Fixed GitlabDiscoveryEntityProvider to only process push events targeting the configured branch. Contributed by @iamEAP in #35255.
  • The GitHub multi-org entity provider now logs a clear warning when no GitHub App installation is found for an org. Contributed by @Dasmat13 in #34833.
  • Fixed the scaffolder task worker silently giving up after a transient failure, where a single error while picking up a task would stop the backend from running any further templates. Contributed by @Mahanmmi in #35359.
  • The workspace:template* actions are now exported by default. Contributed by @mbenson in #34915.
  • Restored support for intrinsic string, number, array, Map, and Set methods in software templates.
  • Software template inline conditionals without an else branch now render an empty string when their condition is false, matching Nunjucks behavior.
  • Fixed a connection leak in the scaffolder event stream where unsubscribing did not abort the underlying SSE connection. Contributed by @carlerikjohan in #35401.
  • Fixed several issues with scaffolder task event stream reconnection. Contributed by @carlerikjohan in #35401.
  • Fixed the scaffolder wizard not scrolling to the top on step change in the new frontend system. Contributed by @sohailriyas01 in #35318.
  • The catalog:query-catalog-entities action now accepts limit and offset as strings, coercing them to numbers before validation. Contributed by @anshgoyalevil in #34954.
  • Fixed AwsS3UrlReader and AwsCodeCommitUrlReader to resolve account-specific AWS credentials when an assume role ARN is configured. Contributed by @beatleboy501 in #34938.
  • Added optional accountId config to search.elasticsearch for resolving account-specific AWS credentials. Contributed by @beatleboy501 in #34938.
  • Fixed Bitbucket Server file operations failing when the branch name contains special characters. Contributed by @suletetes in #35638.
  • Fixed reading a duration from configuration so that an all-zero ISO 8601 duration yields a consistent zero value. Contributed by @suletetes in #35542.
  • Fixed catalog model relations to inherit the source entity namespace when no default namespace is configured.
  • Fixed a bug where catalog entities could fail to process when catalog model sources mix backstage.io/v1alpha1 and backstage.io/v1beta1 for the same kind. Contributed by @GabDug in #34552.
  • Fixed WebSocket upgrade error responses in the signals backend to prevent load balancers from returning 502 on auth failures. Contributed by @jlawrie in #34761.
  • Fixed accumulating abort listeners on MicrosoftGraphClient. Contributed by @csuich2 in #35321.
  • Fixed CardExtension to avoid requiring app context when a custom Renderer is provided. Contributed by @ciiay in #34869.
  • Fixed AWS S3 publishing to paginate existing objects to properly remove all stale TechDocs files. Contributed by @alecjacobs5401 in #35391.
  • Fixed local TechDocs generation when temporary source paths resolve through filesystem aliases.
  • Use the catalog presentation API for TechDocs document titles and owner labels. Contributed by @AarishMansur in #34760.
  • Fixed techdocs-cli serve silently stopping live reload detection with click 8.3.x. Contributed by @GabDug in #35160.
  • Fixed home clock configuration handling. Contributed by @NithinU2802 in #35192.
  • Fixed ownership card catalog links to filter by stable entity references instead of display titles.
  • Added resolveNotificationLink utility for resolving relative notification links to absolute URLs. Contributed by @gaelgoth in #33845.
  • Added support for calling Connections find without authMethods. Contributed by @neoreddog in #35253.
  • The JSON Schema exported for filter predicates can now be compiled by RE2-based validators. Contributed by @rhart in #35631.
  • Added Kubernetes actions to get clusters and entity resources. Contributed by @drodil in #33832.
  • Increased the test database cleanup timeout to 60 seconds. Contributed by @mtlewis in #35607.
  • Significantly improved the performance of build-workspace when packaging many Backstage packages.

Security Fixes​

This release contains security fixes for the following packages, please upgrade to the latest versions:

  • @backstage/plugin-auth-backend-module-cloudflare-access-provider
  • @backstage/plugin-auth-backend-module-oidc-provider
  • @backstage/plugin-auth-node
  • @backstage/plugin-catalog-backend-module-bitbucket-server
  • @backstage/plugin-proxy-backend
  • @backstage/plugin-scaffolder-backend-module-sentry
  • @backstage/plugin-techdocs-node

Contributors​

Big shoutout to all of the amazing folks who contributed to this release: @AarishMansur, @Dasmat13, @Fortune-Ndlovu, @GabDug, @KarimSeoudy, @MFA-G, @Mahanmmi, @Naga15, @Naycon, @NithinU2802, @PG2000, @Yasser-Ameur, @alecjacobs5401, @anshgoyalevil, @apc-kamezaki, @axdotl, @beatleboy501, @carlerikjohan, @ciiay, @csuich2, @deejay1, @djanickova, @dotboris, @drodil, @dyatko, @gabemontero, @gaelgoth, @gustavolira, @hudsonb, @iamEAP, @jkomendant, @jlawrie, @jroebu14, @kersten, @kuangp, @majdsalman2, @mbenson, @michael-todorovic, @mtlewis, @mythrilium, @neoreddog, @piyushtripathi9424, @reachsanjivbhagat-gif, @rhart, @savitojs, @sid200727, @sohailriyas01, @suletetes, @tanaysingh2512, @tobiasp284, @varshini03, @victoriacheng15, @wscheep

Upgrade path​

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

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

Sign up for our newsletter if you want to be informed about what is happening in the world of Backstage.