diff --git a/docs/features/software-templates/authorizing-parameters-steps-and-actions.md b/docs/features/software-templates/authorizing-parameters-steps-and-actions.md index 0ecde1c57e..072f750a14 100644 --- a/docs/features/software-templates/authorizing-parameters-steps-and-actions.md +++ b/docs/features/software-templates/authorizing-parameters-steps-and-actions.md @@ -175,3 +175,58 @@ class ExamplePermissionPolicy implements PermissionPolicy { ``` Although the rules exported by the scaffolder are simple, combining them can help you achieve more complex cases. + +### Authorizing in the New Backend System + +Instead of the changes in `permission.ts` noted in the above example you will make them in your `index.ts`. You will need to create a module where your permission policy will get added. Here is a very simplified example of how to do that: + +```ts title="packages/backend/src/index.ts" +import { createBackendModule } from '@backstage/backend-plugin-api'; +import { BackstageIdentityResponse } from '@backstage/plugin-auth-node'; +import { + PolicyDecision, + AuthorizeResult, +} from '@backstage/plugin-permission-common'; +import { + PermissionPolicy, + PolicyQuery, +} from '@backstage/plugin-permission-node'; +import { policyExtensionPoint } from '@backstage/plugin-permission-node/alpha'; + +class ExamplePermissionPolicy implements PermissionPolicy { + async handle( + request: PolicyQuery, + user?: BackstageIdentityResponse, + ): Promise { + // Various scaffolder permission checks ... + + return { + result: AuthorizeResult.ALLOW, + }; + } +} + +const customPermissionBackendModule = createBackendModule({ + pluginId: 'permission', + moduleId: 'allow-all-policy', + register(reg) { + reg.registerInit({ + deps: { policy: policyExtensionPoint }, + async init({ policy }) { + policy.setPolicy(new ExamplePermissionPolicy()); + }, + }); + }, +}); + +const backend = createBackend(); + +// Other plugins... + +/* highlight-add-start */ +backend.add(import('@backstage/plugin-permission-backend/alpha')); +backend.add(customPermissionBackendModule); +/* highlight-add-end */ +``` + +> Note: the `ExamplePermissionPolicy` here could be the one from the [Authorizing parameters and steps](#authorizing-parameters-and-steps) example or from the [Authorizing actions](#authorizing-actions) example. It would work the same way for both of them. diff --git a/docs/features/software-templates/builtin-actions.md b/docs/features/software-templates/builtin-actions.md index a40caf4c42..53819f67ce 100644 --- a/docs/features/software-templates/builtin-actions.md +++ b/docs/features/software-templates/builtin-actions.md @@ -10,16 +10,18 @@ git repository. ## Action Modules -The GitHub module is included out of the box, but several other modules are available: +There are also several modules available for various SCM tools: - Azure DevOps: `@backstage/plugin-scaffolder-backend-module-azure` - Bitbucket Cloud: `@backstage/plugin-scaffolder-backend-module-bitbucket-cloud` - Bitbucket Server: `@backstage/plugin-scaffolder-backend-module-bitbucket-server` - Gerrit: `@backstage/plugin-scaffolder-backend-module-gerrit` -- Gittea: `@backstage/plugin-scaffolder-backend-module-gittea` +- Gitea: `@backstage/plugin-scaffolder-backend-module-gitea` - GitLab: `@backstage/plugin-scaffolder-backend-module-gitlab` -Here's how to add an action module, this is a simplified backend for example purposes: +## Installing Action Modules + +Here's how to add an action module, this is a simplified new backend system for example purposes: ```ts title="/packages/backend/src/index.ts import { createBackend } from '@backstage/backend-defaults'; diff --git a/docs/features/software-templates/writing-custom-actions.md b/docs/features/software-templates/writing-custom-actions.md index 929ba150d2..92ff092948 100644 --- a/docs/features/software-templates/writing-custom-actions.md +++ b/docs/features/software-templates/writing-custom-actions.md @@ -107,7 +107,7 @@ export const createNewFileAction = () => { }; ``` -#### Naming Conventions +### Naming Conventions Try to keep names consistent for both your own custom actions, and any actions contributed to open source. We've found that a separation of `:` and using a verb as the last part of the name works well. We follow `provider:entity:verb` or as close to this as possible for our built in actions. For example, `github:actions:create` or `github:repo:create`. @@ -189,6 +189,42 @@ export default async function createPlugin( } ``` +### Register Action With New Backend System + +To register your new custom action in the New Backend System you will need to create a backend module. Here is a very simplified example of how to do that: + +```ts title="packages/backend/src/index.ts" +/* highlight-add-start */ +import { scaffolderActionsExtensionPoint } from '@backstage/plugin-scaffolder-node/alpha'; +import { createBackendModule } from '@backstage/backend-plugin-api'; +/* highlight-add-end */ + +/* highlight-add-start */ +const scaffolderModuleCustomExtensions = createBackendModule({ + pluginId: 'scaffolder', // name of the plugin that the module is targeting + moduleId: 'custom-extensions', + register(env) { + env.registerInit({ + deps: { + scaffolder: scaffolderActionsExtensionPoint, + // ... and other dependencies as needed + }, + async init({ scaffolder /* ..., other dependencies */ }) { + // Here you have the opportunity to interact with the extension + // point before the plugin itself gets instantiated + scaffolder.addActions(new createNewFileAction()); // just an example + }, + }); + }, +}); +/* highlight-add-end */ + +const backend = createBackend(); +backend.add(import('@backstage/plugin-scaffolder-backend/alpha')); +/* highlight-add-next-line */ +backend.add(scaffolderModuleCustomExtensions()); +``` + ## List of custom action packages Here is a list of Open Source custom actions that you can add to your Backstage