docs/releases/v1.40.0-changelog.md
Upgrade Helper: https://backstage.github.io/upgrade-helper/?to=1.40.0
33394db: BREAKING CHANGES
Removal of deprecated re-exports from module packages.
The following functions have been re-exported from the scaffolder-backend plugin for quite some time, and now it's time to clean them up. They've been moved as follows:
createPublishAzureAction should be imported from @backstage/plugin-scaffolder-backend-module-azure instead.
createPublishBitbucketCloudAction should be imported from @backstage/plugin-scaffolder-backend-module-bitbucket-cloud instead.
createPublishBitbucketServerAction and createPublishBitbucketServerPullRequestAction can be imported from @backstage/plugin-scaffolder-backend-module-bitbucket-server instead.
createPublishBitbucketAction should be imported from @backstage/plugin-scaffolder-backend-module-bitbucket instead.
createPublishGerritAction and createPublishGerritReviewAction can be imported from @backstage/plugin-scaffolder-backend-module-gerrit instead.
createGithubActionsDispatchAction, createGithubDeployKeyAction, createGithubEnvironmentAction, createGithubIssuesLabelAction, CreateGithubPullRequestActionOptions, createGithubRepoCreateAction, createGithubRepoPushAction, createGithubWebhookAction, and createPublishGithubAction can be imported from @backstage/plugin-scaffolder-backend-module-github instead.
createPublishGitlabAction should be imported from @backstage/plugin-scaffolder-backend-module-gitlab instead.
ActionContext. createTemplateAction, executeShellCommand, ExecuteShellCommandOptions, fetchContents, TaskSecrets, and TemplateAction should be imported from @backstage/plugin-scaffolder-node instead.
ScaffolderEntitiesProcessor should be imported from @backstage/plugin-catalog-backend-module-scaffolder-entity-model instead.
a8fcf04: BREAKING ALPHA: The /alpha export no longer exports the plugin. Please use import('@backstage/plugin-scaffolder-backend') instead as this has been removed.
BREAKING CHANGES: The old createRouter function which was used in the old backend system has been removed along with the RouterOptions type.
73b94d7: BREAKING CHANGES
The following functions have been re-exported from the scaffolder-backend plugin for quite some time, and now it's time to clean them up. They've been moved as follows:
SerializedTask, SerializedTaskEvent, TaskBroker, TaskBrokerDispatchOptions, TaskBrokerDispatchResult, TaskCompletionState, TaskContext, TaskEventType, TaskStatus, TemplateFilter, and TemplateGlobal should be imported from @backstage/plugin-scaffolder-node instead.
The deprecated copyWithoutRender option has been removed from fetch:template action. You should rename the option to copyWithoutTemplating instead.
5863b04: BREAKING CHANGES
The createBuiltinActions method has been removed, as this should no longer be needed with the new backend system route, and was only useful when passing the default list of actions again in the old backend system. You should be able to rely on the default behaviour of the new backend system which is to merge the actions.
The createCatalogRegisterAction and createFetchCatalogEntityAction actions no longer require an AuthService, and now accepts a CatalogService instead of CatalogClient.
Unless you're providing your own override action to the default, this should be a non-breaking change.
You can migrate using the following if you're getting typescript errors:
import { catalogServiceRef } from '@backstage/plugin-catalog-node';
import { scaffolderActionsExtensionPoint } from '@backstage/plugin-scaffolder-node/alpha';
export const myModule = createBackendModule({
pluginId: 'scaffolder',
moduleId: 'test',
register({ registerInit }) {
registerInit({
deps: {
scaffolder: scaffolderActionsExtensionPoint,
catalog: catalogServiceRef,
},
async init({ scaffolder, catalog }) {
scaffolder.addActions(
createCatalogRegisterAction({
catalog,
}),
createFetchCatalogEntityAction({
catalog,
integrations,
}),
);
},
});
},
});
73b94d7: DEPRECATIONS
The following types and implementations have been deprecated, either because they're no longer relevant, or because upcoming changes to the scaffolder-backend after 2.0.0 will influence the changes to these API surfaces.
CreateWorkerOptionsDatabaseTaskStoreDatabaseTaskStoreOptionsTaskManagerTaskStoreCreateTaskOptionsTaskStoreCreateTaskResultTaskStoreEmitOptionsTaskStoreListEventsOptionsTaskStoreRecoverTaskOptionsTaskStoreShutDownTaskOptionsThere is no current path off deprecation, these types are going to be removed and rethought with a better way to define workers in the new backend system.
89a941d: Migrating to latest action format
023629e: Enable usage of secrets within 'each' step of software templates. For example, you can now structure your each step like this:
each:
[
{ name: "Service1", token: "${{ secrets.token1 }}" },
{ name: "Service2", token: "${{ secrets.token2 }}" },
]
e92e481: Add tests for Scaffolder
Updated dependencies
1220cf8: Added new rate limit middleware to allow rate limiting requests to the backend
If you are using the configure callback of the root HTTP router service and do NOT call applyDefaults() inside it, please see the relevant changes that were made, to see if you want to apply them as well to your custom configuration.
Rate limiting can be turned on by adding the following configuration to app-config.yaml:
backend:
rateLimit:
window: 6s
incomingRequestLimit: 100
Plugin specific rate limiting can be configured by adding the following configuration to app-config.yaml:
backend:
rateLimit:
global: false # This will disable the global rate limiting
plugin:
catalog:
window: 6s
incomingRequestLimit: 100
c999c25: Added some default implementations for the experimental ActionsService and ActionsRegistryService under /alpha that allow registration of actions for a particular plugin.
Updated dependencies
664c07a: Added actionsRegistry and actions experimental services to /alpha to allow registration of distributed actions from plugins, and the ability to invoke these actions. You can use these services by including them like the following:
import {
actionsRegistryServiceRef,
actionsServiceRef,
} from '@backstage/backend-plugin-api/alpha';
createBackendPlugin({
pluginId: 'test-plugin',
register({ registerInit }) {
registerInit({
deps: {
actions: actionsServiceRef,
actionsRegistry: actionsRegistryServiceRef,
},
async init({ actions, actionsRegistry }) {
actionsRegistry.register({
...,
});
await actions.invoke(...);
},
});
},
});
6dfb7be: Added mockServices.permissions() that can return actual results.
c999c25: Added an actionsRegistryServiceMock and actionsServiceMock to /alpha export for the experimental services.
This allows you to write tests for your actions by doing something similar to the following:
import { actionsRegistryServiceMock } from '@backstage/backend-test-utils/alpha';
const mockActionsRegistry = actionsRegistryServiceMock();
const mockCatalog = catalogServiceMock({
entities: [
...
],
});
createGetCatalogEntityAction({
catalog: mockCatalog,
actionsRegistry: mockActionsRegistry,
});
await expect(
mockActionsRegistry.invoke({
id: 'test:get-catalog-entity',
input: { name: 'test' },
}),
).resolves.toEqual(...)
user credentials mock behave more like productionBACKSTAGE_CLI_EXPERIMENTAL_BUILD_CACHE flag has been removed. Existing users are encouraged to switch to EXPERIMENTAL_RSPACK instead.ModuleFederationPlugin from @module-federation/enhanced/rspack for Rspack, rather than the built-in one.FORCE_REACT_DEVELOPMENT flag has been removed.zod schemabackstage.pluginId field in package.json to all default plugin package templates for the new command.build and start modules.package-docs command.enum schema values.backstage-repo-tools schema openapi generate without the --watch flag.package-docs command.@electric-sql/pglite to ^0.3.0.406acb6: Add support to customize the about card icon links via EntityIconLinkBlueprint and provide a default catalog view catalog source, launch scaffolder template and read techdocs docs icon links extensions.
BREAKING ALPHA
The Scaffolder launch template and TechDocs read documentation icons have been extracted from the default Catalog about card links and are now provided respectively by the Scaffolder and TechDocs plugins in the new frontend system. It means that they will not be available unless you install the TechDocs and Scaffolder plugins. Also If you are using translation for these icon link titles other than the default, you should now translate them using the scaffolder translation reference or the TechDocs translation reference (the translation keys are still the same, aboutCard.viewTechdocs and aboutCard.launchTemplate).
ec7b35d: Introduced backstage.io/techdocs-entity-path annotation which allows deep linking into another entities TechDocs in conjunction with backstage.io/techdocs-entity.
info.packageJson option to the plugin instance for the new frontend system.get-catalog-entity with the ActionsRegistryHAS_LABEL permission rule, similar to the HAS_ANNOTATION permission rule.refresh_state_references.id to be a big intBitbucketCloudEntityProvider now accepts a CatalogService instead of a CatalogApi.restrictUsersToGroup: true in app-config under your module settings.406acb6: Introduces a new EntityIconLinkBlueprint that customizes the About card icon links on the Catalog entity page.
The blueprint currently accepts a useProps hook as param and this function returns the following props that will be passed to the icon link component:
| Name | Description | Type | Default Value |
|---|---|---|---|
icon | The icon to display. | JSX.Element | N/A |
label | The label for the element. | string | N/A |
title | The title for the element. | string | N/A |
disabled | Whether the element is disabled. | boolean | false |
href | The URL to navigate to when the element is clicked. | string | N/A |
onClick | A function to call when the element is clicked. | () => void | N/A |
Here is an usage example:
import { EntityIconLinkBlueprint } from '@backstage/plugin-catalog-react/alpha';
//...
EntityIconLinkBlueprint.make({
name: 'my-icon-link',
params: {
useProps() {
const { t } = useTranslationRef(myIconLinkTranslationRef);
return {
label: t('myIconLink.label'),
icon: <MyIconLinkIcon />,
href: '/my-plugin',
};
},
},
});
Additionally, the app-config.yaml file allows you to override some of the default icon link parameters, including label and title values. Here's how to set them:
app:
extensions:
- entity-icon-link:my-plugin/my-icon-link:
config:
label: 'My Custom Icon Link label'
Finally, you can disable all links if you want to hide the About card header completely (useful, for example, when links are displayed on separate cards). The header is hidden when no icon links extensions are enabled.
b034b9d: Adds a new module kafka for plugin-events-backend
The module introduces the KafkaConsumerClient which creates a Kafka client used to establish consumer connections. It also provides the KafkaConsumingEventPublisher, a consumer that subscribes to configured Kafka topics and publishes received messages to the Event Service.
mcp-actions backendentityRef and taskId to the analytics events whenever is possible.Scaffolder plugin is now responsible for providing an entity icon link extension to launch templates from the catalog entity page.info.packageJson option to the plugin instance for the new frontend system.5863b04: BREAKING CHANGES
The createGithubEnvironmentAction action no longer requires an AuthService, and now accepts a CatalogService instead of CatalogClient.
Unless you're providing your own override action to the default, this should be a non-breaking change.
You can migrate using the following if you're getting typescript errors:
import { catalogServiceRef } from '@backstage/plugin-catalog-node';
import { scaffolderActionsExtensionPoint } from '@backstage/plugin-scaffolder-node/alpha';
export const myModule = createBackendModule({
pluginId: 'scaffolder',
moduleId: 'test',
register({ registerInit }) {
registerInit({
deps: {
scaffolder: scaffolderActionsExtensionPoint,
catalog: catalogServiceRef,
},
async init({ scaffolder, catalog }) {
scaffolder.addActions(
createGithubEnvironmentAction({
catalog,
}),
);
},
});
},
});
5863b04: BREAKING CHANGES
The legacy methods to define createTemplateActions have been replaced with the new native zod approaches for defining input and output schemas.
You can migrate actions that look like the following with the below examples:
// really old legacy json schema
createTemplateAction<{ repoUrl: string }, { repoOutput: string }>({
id: 'test',
schema: {
input: {
type: 'object'
required: ['repoUrl']
properties: {
repoUrl: {
type: 'string',
description: 'repository url description'
}
}
}
}
});
// old zod method
createTemplateAction({
id: 'test'
schema: {
input: {
repoUrl: z.string({ description: 'repository url description' })
}
}
})
// new method:
createTemplateAction({
id: 'test',
schema: {
input: {
repoUrl: z => z.string({ description: 'repository url description' })
}
}
})
// or for more complex zod types like unions
createTemplateAction({
id: 'test',
schema: {
input: z => z.object({
repoUrl: z.string({ description: 'repository url description' })
})
}
})
This breaking change also means that logStream has been removed entirely from ActionsContext, and that the logger is now just a LoggerService implementation instead. There is no replacement for the logStream, if you wish to still keep using a logStream we recommend that you create your own stream that writes to ctx.logger instead.
LoggerService instead of Logger. This is a non-breaking change, as the LoggerService is a subset of the Logger interface.3cea7ee: BREAKING CHANGES
Because of the removal of the logStream property to the ActionsContext this has been removed from the createMockActionContext method.
You can remove this as it's no longer supported in the scaffolder actions.
entityRef and taskId to the analytics events whenever is possible.TechDocs plugin is now responsible for providing an entity icon link extension to read documentation from the catalog entity page.backstage.io/techdocs-entity-path annotation which allows deep linking into another entities TechDocs in conjunction with backstage.io/techdocs-entity.info.packageJson option to the plugin instance for the new frontend system.backstage.io/techdocs-entity-path annotation which allows deep linking into another entities TechDocs in conjunction with backstage.io/techdocs-entity.CatalogClient error responses for refreshEntity and addLocation.098ef95: Fix custom rules package scanning performance.
063b2d3: Added new eslint rule to restrict mixed plugin imports.
New rule @backstage/no-mixed-plugin-imports disallows mixed imports between plugins that are mixing
the backstage architecture. This rule forces that:
The current recommended configuration is giving a warning for mixed imports. This is to be changed in the future to an error so please adjust your workspace accordingly.
plugin.info() method in specialized apps with a default resolved for package.json and catalog-info.yaml. The default resolution logic can be overridden via the pluginInfoResolver option to createSpecializedApp, and plugin-specific overrides can be applied via the new app.pluginOverrides key in static configuration.pluginInfoResolver option for createApp.0169b23: Internal tweak to avoid circular dependencies
9e3868f: Added a new optional info option to createFrontendPlugin that lets you provide a loaders for different sources of metadata information about the plugin.
There are two available loaders. The first one is info.packageJson, which can be used to point to a package.json file for the plugin. This is recommended for any plugin that is defined within its own package, especially all plugins that are published to a package registry. Typical usage looks like this:
export default createFrontendPlugin({
pluginId: '...',
info: {
packageJson: () => import('../package.json'),
},
});
The second loader is info.manifest, which can be used to point to an opaque plugin manifest. This MUST ONLY be used by plugins that are intended for use within a single organization. Plugins that are published to an open package registry should NOT use this loader. The loader is useful for adding additional internal metadata associated with the plugin, and it is up to the Backstage app to decide how these manifests are parsed and used. The default manifest parser in an app created with createApp from @backstage/frontend-defaults is able to parse the default catalog-info.yaml format and built-in fields such as spec.owner.
Typical usage looks like this:
export default createFrontendPlugin({
pluginId: '...',
info: {
manifest: () => import('../catalog-info.yaml'),
},
});
6f48f71: Added a new useAppNode hook, which can be used to get a reference to the AppNode from by the closest ExtensionBoundary.
Updated dependencies
info.packageJson option to the plugin instance for the new frontend system.info.packageJson option to the plugin instance for the new frontend system.info.packageJson option to the plugin instance for the new frontend system.@davidzemon/passport-okta-oauth to ^0.0.6.087d51d: Export LDAP vendor types and instances for testing custom transformers
f07b0ad: Added the ability to configure disabling one side of the relations tree with LDAP.
Groups have a member attribute and users have a memberOf attribute, however these can drift out of sync in some LDAP installations, leaving weird states in the Catalog as we collate these results together and deduplicate them.
You can chose to optionally disable one side of these relationships, or even both by setting the respective mapping to null in your app-config.yaml for your groups and/or users:
catalog:
providers:
ldapOrg:
default:
target: ldaps://ds.example.net
bind:
dn: uid=ldap-reader-user,ou=people,ou=example,dc=example,dc=net
secret: ${LDAP_SECRET}
users:
- dn: ou=people,ou=example,dc=example,dc=net
options:
filter: (uid=*)
map:
# this ensures that outgoing memberships from users is ignored
memberOf: null
groups:
- dn: ou=access,ou=groups,ou=example,dc=example,dc=net
options:
filter: (&(objectClass=some-group-class)(!(groupType=email)))
map:
description: l
set:
metadata.customField: 'hello'
map:
# this ensures that outgoing memberships from groups is ignored
members: null
Updated dependencies
info.packageJson option to the plugin instance for the new frontend system.info.packageJson option to the plugin instance for the new frontend system.info.packageJson option to the plugin instance for the new frontend system.info.packageJson option to the plugin instance for the new frontend system.permissionIntegrationRouter in favor of using the new coreServices.permissionsRegistryEventConsumingGooglePubSubPublisher, for pushing Backstage events to pubsubinfo.packageJson option to the plugin instance for the new frontend system.WelcomeTitle to properly default to the previous value of inheritinfo.packageJson option to the plugin instance for the new frontend system.info.packageJson option to the plugin instance for the new frontend system.41d4d6e: Notifications are now automatically deleted after 1 year by default.
There is a new scheduled task that runs every 24 hours to delete notifications older than 1 year.
This can be configured by setting the notifications.retention in the app-config.yaml file.
notifications:
retention: 1y
If the retention is set to false, notifications will not be automatically deleted.
8a150bf: Internal changes to switch to the non-alpha catalogServiceRef
1fb5f06: Adds ability for user to turn on/off notifications for specific topics within an origin.
ef9ab82: Notifications API will now return user as null always for broadcast notifications
Updated dependencies
catalogServiceRefinfo.packageJson option to the plugin instance for the new frontend system.azure actions to using the new zod schema formatbitbucket actions to use the new zod formatbitbucket-cloud to new actions formatbitbucketCloudBranchRestrictions API calls to accept null to prevent 400 errors for some branch restriction kinds defined.octokit dependency as it was not being usedinfo.packageJson option to the plugin instance for the new frontend system.info.packageJson option to the plugin instance for the new frontend system.backstage.io/techdocs-entity-path annotation which allows deep linking into another entities TechDocs in conjunction with backstage.io/techdocs-entity.info.packageJson option to the plugin instance for the new frontend system.