docs/releases/v1.49.0-next.1-changelog.md
Upgrade Helper: https://backstage.github.io/upgrade-helper/?to=1.49.0-next.1
527cf88: BREAKING Removed deprecated Azure DevOps, Bitbucket, Gerrit and GitHub code:
token string and credential object have been removed from the config.d.ts. Use the credentials array object instead.bitbucket object has been removed from the config.d.ts. Use the bitbucketCloud or bitbucketServer objects instead.parseGerritGitilesUrl function has been removed, use parseGitilesUrlRef instead. The buildGerritGitilesArchiveUrl function has also been removed, use buildGerritGitilesArchiveUrlFromLocation instead.getGitHubRequestOptions function has been removed.@visibility secret instead of @deepVisibility secret on parent objects, so that non-secret fields like clientId, tenantId, organizations, and managedIdentityClientId are no longer incorrectly marked as secret.bitbucket integration from being registered in the ScaffolderClient. Use the bitbucketCloud or bitbucketServer integrations instead.retry, listTasks, listTemplatingExtensions, dryRun, and autocomplete required methods on the ScaffolderApi interface. Implementations of ScaffolderApi must now provide these methods.BitbucketUrlReader. Use the BitbucketCloudUrlReader or the BitbucketServerUrlReader instead.InputError and NotFoundError thrown by actions preserve their original status codes and messages instead of being wrapped in ForwardedError and coerced to 500.972f686: Added support for the query field in getEntitiesByRefs requests, enabling predicate-based filtering with $all, $any, $not, $exists, $in, $contains, and $hasPrefix operators.
56c908e: Added support for the query field in getEntityFacets requests, enabling predicate-based filtering with $all, $any, $not, $exists, $in, $contains, and $hasPrefix operators.
0fbcf23: Migrated OpenAPI schemas to 3.1.
51e23eb: Added predicate-based entity filtering via POST /entities/by-query endpoint.
Supports $all, $any, $not, $exists, $in, $hasPrefix, and (partially) $contains operators for expressive entity queries. Integrated into the existing queryEntities flow with full cursor-based pagination, permission enforcement, and totalItems support.
The catalog client's queryEntities() method automatically routes to the POST endpoint when a query predicate is provided.
migrate package-exports command has been removed. Use repo fix instead.loadCliConfig into separate implementations for the build and config CLI modules, removing a cross-module dependency.@backstage/cli-node instead of a local implementation.package.json workspaces fieldschema openapi commands. The commands now auto-detect the OpenAPI version from the spec file and use the appropriate generator, supporting both OpenAPI 3.0.x and 3.1.x specifications.generate-catalog-info command failing with "too many arguments" when invoked by lint-staged via the pre-commit hook.768f09d: BREAKING: Simplified the neutral background prop API for container components. The explicit neutral-1, neutral-2, neutral-3, and neutral-auto values have been removed from ProviderBg. They are replaced by a single 'neutral' value that always auto-increments from the parent context, making it impossible to skip or pin to an explicit neutral level.
Migration:
Replace any explicit bg="neutral-1", bg="neutral-2", bg="neutral-3", or bg="neutral-auto" props with bg="neutral". To achieve a specific neutral level in stories or tests, use nested containers — each additional bg="neutral" wrapper increments by one level.
// Before
<Box bg="neutral-2">...</Box>
// After
<Box bg="neutral">
<Box bg="neutral">...</Box>
</Box>
Affected components: Box, Flex, Grid, Card, Accordion, Popover, Tooltip, Dialog, Menu
b42fcdc: BREAKING: Removed --bui-bg-popover CSS token. Popover, Tooltip, Menu, and Dialog now use --bui-bg-app for their outer shell and Box bg="neutral-1" for content areas, providing better theme consistency and eliminating a redundant token.
Migration:
Replace any usage of --bui-bg-popover with --bui-bg-neutral-1 (for content surfaces) or --bui-bg-app (for outer shells):
- background: var(--bui-bg-popover);
+ background: var(--bui-bg-neutral-1);
Affected components: Popover, Tooltip, Menu, Dialog
bd3a76e: BREAKING: Data attributes rendered by components are now always lowercase. This affects CSS selectors targeting camelCase data attributes.
Migration:
Update any custom CSS selectors that target camelCase data attributes to use lowercase instead:
- [data-startCollapsed='true'] { ... }
+ [data-startcollapsed='true'] { ... }
Affected components: SearchField
95702ab: BREAKING: Removed deprecated types ComponentDefinition, ClassNamesMap, DataAttributeValues, and DataAttributesMap from the public API. These were internal styling infrastructure types that have been replaced by the defineComponent system.
Migration:
Remove any direct usage of these types. Component definitions now use defineComponent() and their shapes are not part of the public API contract.
- import type { ComponentDefinition, ClassNamesMap } from '@backstage/ui';
If you were reading definition.dataAttributes, use definition.propDefs instead — props with dataAttribute: true in propDefs are the equivalent.
58224d3: Fixed neutral-1 hover & pressed state in light mode.
95702ab: Migrated all components from useStyles to useDefinition hook. Exported OwnProps types for each component, enabling better type composition for consumers.
Affected components: Avatar, Checkbox, Container, Dialog, FieldError, FieldLabel, Flex, FullPage, Grid, HeaderPage, Link, Menu, PasswordField, PluginHeader, Popover, RadioGroup, SearchField, Select, Skeleton, Switch, Table, TablePagination, Tabs, TagGroup, Text, TextField, ToggleButton, ToggleButtonGroup, Tooltip, VisuallyHidden
4c2c350: Removed the transition on Container padding to prevent an unwanted animation when the viewport is resized.
Affected components: Container
d4fa5b4: Fixed tab matchStrategy matching to ignore query parameters and hash fragments in tab href values. Previously, tabs with query params in their href (e.g., /page?group=foo) would never show as active since matching compared the full href string against location.pathname which never includes query params.
Affected components: Tabs, PluginHeader
36987db: Fixed handling of the style prop on Button, ButtonIcon, and ButtonLink so that it is now correctly forwarded to the underlying element instead of being silently dropped.
Affected components: Button, ButtonIcon, ButtonLink
95702ab: Fixed Link variant default from 'body' to 'body-medium' to match actual CSS selectors. The previous default did not correspond to a valid variant value.
Affected components: Link
9027b10: Fixed scroll overflow in Menu and Select popover content when constrained by viewport height.
Affected components: Menu, Select
4105a78: Merged the internal PluginHeaderToolbar component into PluginHeader, removing the separate component and its associated types (PluginHeaderToolbarOwnProps, PluginHeaderToolbarProps) and definition (PluginHeaderToolbarDefinition). This is an internal refactor with no changes to the public API of PluginHeader.
Affected components: PluginHeader
b303857: Fixed isRequired prop not being passed to the underlying React Aria field components in TextField, SearchField, and PasswordField. Previously, isRequired was consumed locally for the secondary label text but never forwarded, which meant the input elements lacked aria-required="true" and React Aria's built-in required validation was not activated.
Affected components: TextField, SearchField, PasswordField
cd3cb0f: Improved useBreakpoint performance by sharing a single set of matchMedia listeners across all component instances instead of creating independent listeners per hook call.
36987db: Extended AlertProps, ContainerProps, DialogBodyProps, and FieldLabelProps with native div element props to allow passing attributes like aria-* and data-*.
Affected components: Alert, Container, DialogBody, FieldLabel
Updated dependencies
aliases so that content targeting an aliased group is included in the group. A new defaultContentOrder option (default title) controls how content items within each group are sorted, with support for both a page-level default and per-group overrides.groups configuration.a6b2819: Added query-catalog-entities action to the catalog backend actions registry. Supports predicate-based filtering with $all, $any, $not, $exists, $in, $contains, and $hasPrefix operators.
972f686: Added support for predicate-based filtering on the /entities/by-refs endpoint via the query field in the request body. Supports $all, $any, $not, $exists, $in, $contains, and $hasPrefix operators.
56c908e: Added support for predicate-based filtering on the /entity-facets endpoint via a new POST method. Supports $all, $any, $not, $exists, $in, $contains, and $hasPrefix operators.
0fbcf23: Migrated OpenAPI schemas to 3.1.
51e23eb: Added predicate-based entity filtering via POST /entities/by-query endpoint.
Supports $all, $any, $not, $exists, $in, $hasPrefix, and (partially) $contains operators for expressive entity queries. Integrated into the existing queryEntities flow with full cursor-based pagination, permission enforcement, and totalItems support.
The catalog client's queryEntities() method automatically routes to the POST endpoint when a query predicate is provided.
72747b4: Deprecated two processors 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 insteadCodeOwnersProcessor: Use @backstage-community/plugin-catalog-backend-module-codeowners insteadUpdated dependencies
b11c2cd: The default user transformer now prefers organization verified domain emails over the user's public GitHub email when populating the user entity profile. It also strips plus-addressed routing tags that GitHub adds to these emails.
If you want to retain the old behavior, you can do so with a custom user transformer using the githubOrgEntityProviderTransformsExtensionPoint:
import { createBackendModule } from '@backstage/backend-plugin-api';
import { githubOrgEntityProviderTransformsExtensionPoint } from '@backstage/plugin-catalog-backend-module-github-org';
import { defaultUserTransformer } from '@backstage/plugin-catalog-backend-module-github';
export default createBackendModule({
pluginId: 'catalog',
moduleId: 'github-org-custom-transforms',
register(env) {
env.registerInit({
deps: {
transforms: githubOrgEntityProviderTransformsExtensionPoint,
},
async init({ transforms }) {
transforms.setUserTransformer(async (item, ctx) => {
const entity = await defaultUserTransformer(item, ctx);
if (entity && item.email) {
entity.spec.profile!.email = item.email;
}
return entity;
});
},
});
},
});
aliases and contentOrder fields to EntityContentGroupDefinition, allowing groups to declare alias IDs and control the sort order of their content items.list-scaffolder-tasks action that allows querying scaffolder tasks with optional ownership filtering and pagination supportlist-scaffolder-actions action that returns all installed scaffolder actions with their schemas and examples@backstage/plugin-scaffolder-backend-module-bitbucket from package.json as the package itself has been deprecated and the code deleted.bitbucket integration from being used in the parseRepoUrl function. It will use the bitbucketCloud or bitbucketServer integrations instead.scaffolderServiceRef and ScaffolderService interface for backend plugins that need to interact with the scaffolder API using BackstageCredentials instead of raw tokens.InputError and NotFoundError thrown by actions preserve their original status codes and messages instead of being wrapped in ForwardedError and coerced to 500.findOwnRootDir utility now searches for the monorepo root by traversing up the directory tree looking for a package.json with workspaces, instead of assuming a fixed ../.. relative path. If no workspaces root is found during this traversal, findOwnRootDir now throws to enforce stricter validation of the repository layout.toString() method to Lockfile for serializing lockfiles back to string format.hasBackstageYarnPlugin and SuccessCache exports, moved from @backstage/cli.package.json workspaces fielda9d23c4: Properly support package.json workspaces field
ebd4630: Replace deprecated workspaces.packages with workspaces in package.json
This change is not required, but you can edit your main package.json, to fit the more modern & more common pattern:
- "workspaces": {
- "packages": [
"workspaces": [
"packages/*",
"plugins/*"
- ]
- },
],
Updated dependencies
TestApiPair when using tuple syntax by wrapping MockWithApiFactory in NoInfer.@mui/material/styles shared dependency key by removing a trailing slash that caused module resolution failures with MUI package exports.documentation group and the APIs tab defaults to the development group.who-am-i action to the auth backend actions registry. Returns the catalog entity and user info for the currently authenticated user.InputError and NotFoundError thrown by actions preserve their original status codes and messages instead of being wrapped in ForwardedError and coerced to 500.bitbucket integration from repoPickerValidation function used by the RepoUrlPicker, it now validates the bitbucketServer and bitbucketCloud integrations instead.gitlab:group:access scaffolder action to add or remove users and groups as members of GitLab groups. The action supports specifying members via userIds and/or groupIds array parameters, configurable access levels (Guest, Reporter, Developer, Maintainer, Owner), and defaults to the 'add' action when not specified.formFieldsApiRef and ScaffolderFormFieldsApi as alpha exports.scaffolderApiMock test utility, exported from @backstage/plugin-scaffolder-react/testUtils.documentation as the default entity content group for the TechDocs entity content tab.techdocs.generator.mkdocs.dangerouslyAllowAdditionalKeys configuration option to explicitly bypass MkDocs configuration key restrictions. This enables support for additional MkDocs configuration keys beyond the default safe allow list, such as the hooks key which some MkDocs plugins require.techdocs.generator.mkdocs.dangerouslyAllowAdditionalKeys configuration option to explicitly bypass MkDocs configuration key restrictions. This enables support for additional MkDocs configuration keys beyond the default safe allow list, such as the hooks key which some MkDocs plugins require.