Skip to main content
Version: Next

v1.49.0

These are the release notes for the v1.49.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​

New Frontend System: 1.0 Release Candidate​

This release marks the release candidate for version 1.0 of the New Frontend System. Newly created Backstage apps now use the New Frontend System by default, the --next flag for create-app has been replaced with a --legacy flag for apps that still want to use the old system. The yarn new templates have been updated accordingly, with auto-detection that presents the correct plugin templates based on which frontend system your app uses.

On the framework side, this release includes significant stabilization of the API surface. Several deprecated types and options have been removed, PluginWrapperApi has graduated from alpha to stable, and a new builder pattern for createApiRef has been introduced. A full list of API changes can be found in the @backstage/frontend-plugin-api changelog.

Plugin pages across the supported plugins have been migrated to the Backstage UI Header component, aligning the plugin header and page-level navigation patterns across the New Frontend System. A new @backstage/frontend-dev-utils package with a createDevApp helper simplifies the setup of plugin development apps.

Documentation has been overhauled across the board to cover and prioritize the New Frontend System, aligning installation guidance across plugin READMEs, closing gaps with the existing "Plugins" section that is now marked as legacy, and many other changes.

BREAKING: Backstage UI updates​

There are several new additions in Backstage UI, for example new SearchAutocomplete and SearchAutocompleteItem components for building accessible search-with-results patterns. New List and ListRow components built on React Aria's GridList for interactive lists with icons, descriptions, and selection. A virtualized prop added to the Table for rendering large datasets. And much more.

There are also several breaking changes to note:

  • Checkbox: Removed the redundant selected and indeterminate props. Use isSelected and isIndeterminate instead, which are the standard React Aria props.
  • Header CSS classes: Renamed internal CSS classes to match the Header component name (e.g. bui-HeaderPage → bui-Header).
  • BUIProvider routing: Centralized client-side routing in BUIProvider. Components like Link, ButtonLink, Tabs, Menu, and Table now require a BUIProvider inside a React Router context for client-side navigation to work.
  • Data attributes: Data attributes rendered by components are now always lowercase, affecting CSS selectors targeting camelCase attributes.
  • Removed deprecated types: ComponentDefinition, ClassNamesMap, DataAttributeValues, and DataAttributesMap have been removed from the public API.
  • Popover token: Removed --bui-bg-popover CSS token. Use --bui-bg-neutral-1 or --bui-bg-app instead.
  • Neutral background: Simplified the neutral background prop API. Explicit neutral-1, neutral-2, neutral-3, and neutral-auto values have been replaced by a single neutral value that auto-increments from the parent context.

Check the BUI Changelog for more details.

BREAKING: Entity cards migrated to Backstage UI​

The @backstage/plugin-catalog package has received a major version bump as EntityAboutCard, EntityLinksCard, EntityLabelsCard, GroupProfileCard, and UserProfileCard have been migrated from MUI to BUI. The variant prop has been removed from these cards, and the gridSizes prop has been removed from AboutField.

Additionally, entity table cards like HasComponentsCard, HasResourcesCard, HasSubcomponentsCard, and others now render with BUI when no legacy props are passed. The old variant, columns, and tableOptions props are deprecated but still supported — passing them triggers the legacy MUI rendering. RelatedEntitiesCard is deprecated in favor of the new EntityRelationCard from @backstage/plugin-catalog-react/alpha.

MembersListCard, OwnershipCard, and CatalogGraphCard from @backstage/plugin-org and @backstage/plugin-catalog-graph have also been migrated to BUI card primitives via EntityInfoCard. The variant prop has been removed from these cards.

- <EntityAboutCard variant="gridItem" />
+ <EntityAboutCard />

BREAKING: Deprecated Bitbucket and legacy integrations removed​

Several long-deprecated integrations have been cleaned up across the project.

In @backstage/integration, the deprecated bitbucket config object, Azure DevOps token/credential fields, parseGerritGitilesUrl, buildGerritGitilesArchiveUrl, and getGitHubRequestOptions have all been removed. Use bitbucketCloud/bitbucketServer, the credentials array, parseGitilesUrlRef/buildGerritGitilesArchiveUrlFromLocation, respectively.

In @backstage/backend-defaults, the deprecated BitbucketUrlReader has been removed. Use BitbucketCloudUrlReader or BitbucketServerUrlReader instead.

In @backstage/plugin-scaffolder-node, the deprecated bitbucket integration has been removed from parseRepoUrl. It now uses bitbucketCloud or bitbucketServer.

In @backstage/plugin-scaffolder-common, the deprecated bitbucket integration has been removed from ScaffolderClient.

BREAKING PRODUCERS: ScaffolderApi methods now required​

The retry, listTasks, listTemplatingExtensions, dryRun, and autocomplete methods are now required on the ScaffolderApi interface. Implementations must provide all of these methods.

BREAKING: Slack notifications direct messages​

The @backstage/plugin-notifications-backend-module-slack module now only sends direct messages to user entity recipients. Notifications sent to non-user entities no longer trigger Slack direct messages.

Contributed by @kaidubauskas-dd in #32619.

AI and MCP improvements​

This release significantly expands the set of built-in actions available for AI agents and MCP consumers. New actions include who-am-i for identifying the authenticated user, query-catalog-entities for predicate-based catalog queries, list-scaffolder-actions for discovering available scaffolder actions with their schemas, list-scaffolder-tasks for querying scaffolder tasks with ownership filtering, and get-scaffolder-task-logs for retrieving log events from running tasks.

The MCP actions backend now supports splitting actions into multiple servers via mcpActions.servers configuration, with include/exclude filter rules per server. Added mcpActions.name and mcpActions.description config options for customizing server identity, and tool names now use dot separators to align with the MCP spec convention. Error forwarding has also been improved so that known errors preserve their original status codes.

A new actions CLI module provides actions list, actions execute, and actions sources commands for interacting with the actions registry directly from the terminal.

See the AI documentation for more information on using Backstage with AI agents.

CLI Module System​

The Backstage CLI has been refactored into an extensible module system. CLI commands are now provided by individual cli-module packages that are discovered automatically from your project's dependencies. This release includes the initial set of CLI modules:

  • @backstage/cli-module-auth
  • @backstage/cli-module-actions
  • @backstage/cli-module-build
  • @backstage/cli-module-config
  • @backstage/cli-module-github
  • @backstage/cli-module-info
  • @backstage/cli-module-lint
  • @backstage/cli-module-maintenance
  • @backstage/cli-module-migrate
  • @backstage/cli-module-new
  • @backstage/cli-module-test-jest
  • @backstage/cli-module-translations

If no CLI modules are found in project dependencies, the CLI falls back to the built-in set with a deprecation warning. To prepare for the removal of this fallback, add @backstage/cli-defaults as a devDependency:

{
  "devDependencies": {
    "@backstage/cli-defaults": "backstage:^"
  }
}

A new createCliModule API in @backstage/cli-node enables third-party CLI modules, and a cli-module template is available via yarn new.

CLI Auth Commands​

A new auth command group has been added for authenticating the CLI with Backstage instances using OAuth 2.0. Commands include login, logout, list, show, print-token, and select for managing multiple authenticated instances. An API for interacting with the selected and specific instance and the authentication sessions towards them has been added to @backstage/cli-node grouped under the CliAuth export.

package bundle Command​

A new package bundle command has been added to @backstage/cli-module-build for creating self-contained plugin bundles for dynamic loading, to be used by the backend-dynamic-feature-service.

Contributed by @davidfestal in #33125.

Predicate-based catalog entity filtering​

A powerful new predicate-based filtering system has been added to the catalog. The catalog client's queryEntities(), getEntitiesByRefs(), and getEntityFacets() methods now support a query field with operators like $all, $any, $not, $exists, $in, $hasPrefix, and $contains for expressive entity queries.

These are exposed through new POST endpoints with full pagination and permission enforcement support. A new query-catalog-entities action has been added for predicate-based catalog queries via the actions system.

Actions: Permissions and user invocation​

Backend actions now support permission-based visibility. An optional visibilityPermission field has been added to ActionsRegistryActionOptions, allowing actions to declare a permission that controls access.

The actions registry invoke endpoint now also accepts direct user credentials in addition to service principals, enabling CLI and other direct user clients to invoke actions.

New ToastApi for rich notifications​

A new ToastApi has been introduced in the New Frontend System for displaying rich toast notifications. Toasts support titles, descriptions, custom timeouts, action links, and status variants (neutral, info, success, warning, danger). They can also be dismissed programmatically.

const toastApi = useApi(toastApiRef);

toastApi.post({
  title: 'Entity saved',
  description: 'Your changes have been saved successfully.',
  status: 'success',
  timeout: 5000,
  links: [{ label: 'View entity', href: '/catalog/entity' }],
});

The ToastDisplay component subscribes to both ToastApi and the existing AlertApi, providing a migration path. The AlertApi, AlertMessage, alertApiRef, and AlertApiForwarder have been deprecated in favor of ToastApi.

Template secrets schema validation​

Templates can now define a secrets.schema field in TemplateEntityV1beta3 for validating secrets provided during task creation. The scaffolder backend validates secrets against the schema and returns a 400 error if validation fails.

Scheduler cancelTask​

A new cancelTask method has been added to the SchedulerService interface and implementation, allowing cancellation of currently running scheduled tasks. A corresponding cancel button has been added to the DevTools scheduled tasks UI.

Entity page group aliases and content ordering​

Entity page groups can now declare aliases so that content targeting an aliased group is included in the group. A new defaultContentOrder option controls how content items within each group are sorted, with support for both page-level and per-group overrides.

LogViewer download support​

The LogViewer component now supports downloading logs via an onDownloadLogs callback.

Contributed by @0xts in #31989.

Translation refs promoted to stable​

Translation refs across 18 packages have been promoted from alpha-only exports to the stable entry points. If you are importing translation refs from /alpha entry points, for example import { catalogTranslationRef } from '@backstage/plugin-catalog/alpha', you can now import them directly from the main package entry point instead. The alpha re-exports are still available but deprecated.

Permission batching​

Permission checks made in the same tick are now batched into a single call to the permission backend, improving performance for pages with many permission-gated elements.

GitHub org verified email preference​

The default user transformer for githubOrg now prefers organization verified domain emails over the user's public GitHub email. A new defaultUserTransformer.useVerifiedEmails config option controls this behavior for the config-based provider.

GitLab integration improvements​

Added configurable throttling and retry mechanism for GitLab integration.

Contributed by @JohannesWill in #30804.

Added a new gitlab:group:access scaffolder action for managing GitLab group memberships.

Contributed by @Jellyfrog in #32528.

Added maskedAndHidden option to gitlab:projectVariable:create and publish:gitlab.

Contributed by @hyfc in #32818.

Custom Slack message layouts​

Added an extension for custom Slack message layouts in the notifications backend Slack module.

Contributed by @kaidubauskas-dd in #32733.

OpenAPI 3.1 support​

OpenAPI schemas across several packages have been migrated to version 3.1. The schema openapi commands in @backstage/repo-tools now auto-detect the OpenAPI version and support both 3.0.x and 3.1.x specifications.

Deprecated Catalog Processors & New Community Plugin Backend Modules​

Two Catalog processors have been deprecated as they have been moved to the Community Plugins repo with their own backend modules:

  • AnnotateScmSlugEntityProcessor: Use @backstage-community/plugin-catalog-backend-module-annotate-scm-slug instead
  • CodeOwnersProcessor: Use @backstage-community/plugin-catalog-backend-module-codeowners instead

Security Fixes​

This release does not contain any security fixes.

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.