paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 31 Packages Projects Releases Wiki Activity

docs: add v1.49.0 release notes

Browse Source 
Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
Made-with: Cursor
This commit is contained in:
Patrik Oldsberg
2026-03-17 20:25:00 +01:00
parent df15d409a4
commit 37f91e926f
2 changed files with 234 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/vale/config/vocabularies/Backstage/accept.txt
+1
View File
@@ -31,6 +31,7 @@ backported
backporting
BEPs
bg
BUIProvider
bigint
Bigtable
Billett
docs/releases/v1.49.0.md
+233
View File
@@ -0,0 +1,233 @@
---
id: v1.49.0
title: v1.49.0
description: Backstage Release v1.49.0
---
These are the release notes for the v1.49.0 release of [Backstage](https://backstage.io/).
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](https://github.com/backstage/backstage/blob/master/packages/frontend-plugin-api/CHANGELOG.md).
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](https://ui.backstage.io/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.
```diff
- <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](https://github.com/kaidubauskas-dd) in [#32619](https://github.com/backstage/backstage/pull/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](https://backstage.io/docs/ai/generated-index) 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`:
```json
{
"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](https://github.com/davidfestal) in [#33125](https://github.com/backstage/backstage/pull/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.
```typescript
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](https://github.com/0xts) in [#31989](https://github.com/backstage/backstage/pull/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](https://github.com/JohannesWill) in [#30804](https://github.com/backstage/backstage/pull/30804).
Added a new `gitlab:group:access` scaffolder action for managing GitLab group memberships.
Contributed by [@Jellyfrog](https://github.com/Jellyfrog) in [#32528](https://github.com/backstage/backstage/pull/32528).
Added `maskedAndHidden` option to `gitlab:projectVariable:create` and `publish:gitlab`.
Contributed by [@hyfc](https://github.com/hyfc) in [#32818](https://github.com/backstage/backstage/pull/32818).
### Custom Slack message layouts
Added an extension for custom Slack message layouts in the notifications backend Slack module.
Contributed by [@kaidubauskas-dd](https://github.com/kaidubauskas-dd) in [#32733](https://github.com/backstage/backstage/pull/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](https://backstage.io/docs/getting-started/keeping-backstage-updated).
## Links and References
Below you can find a list of links and references to help you learn about and start using this new release.
- [Backstage official website](https://backstage.io/), [documentation](https://backstage.io/docs/), and [getting started guide](https://backstage.io/docs/getting-started/)
- [GitHub repository](https://github.com/backstage/backstage)
- Backstage's [versioning and support policy](https://backstage.io/docs/overview/versioning-policy)
- [Community Discord](https://discord.gg/backstage-687207715902193673) for discussions and support
- [Changelog](https://github.com/backstage/backstage/tree/master/docs/releases/v1.49.0-changelog.md)
- Backstage [Demos](https://backstage.io/demos), [Blog](https://backstage.io/blog), [Roadmap](https://backstage.io/docs/overview/roadmap) and [Plugins](https://backstage.io/plugins)
Sign up for our [newsletter](https://spoti.fi/backstagenewsletter) if you want to be informed about what is happening in the world of Backstage.