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 1b3a53b5d9..94b2d2298b 100644 --- a/docs/features/software-templates/builtin-actions.md +++ b/docs/features/software-templates/builtin-actions.md @@ -8,8 +8,58 @@ The scaffolder comes with several built-in actions for fetching content, registering in the catalog and of course actions for creating and publishing a git repository. -There are several repository providers supported out of the box such as GitHub, -Azure, GitLab and Bitbucket. +## Action Modules + +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` +- Gitea: `@backstage/plugin-scaffolder-backend-module-gitea` +- GitHub: `@backstage/plugin-scaffolder-backend-module-github` +- GitLab: `@backstage/plugin-scaffolder-backend-module-gitlab` + +## Installing Action Modules + +Here's how to add an action module, first you need to run this command: + +```sh +# From your Backstage root directory +yarn --cwd packages/backend add @backstage/plugin-scaffolder-backend-module-github +``` + +Then you need to add it to your backend, this is a simplified new backend system for example purposes: + +```ts title="/packages/backend/src/index.ts" +import { createBackend } from '@backstage/backend-defaults'; + +const backend = createBackend(); + +backend.add(import('@backstage/plugin-app-backend/alpha')); + +// catalog plugin +backend.add(import('@backstage/plugin-catalog-backend/alpha')); +backend.add( + import('@backstage/plugin-catalog-backend-module-scaffolder-entity-model'), +); + +// scaffolder plugin +backend.add(import('@backstage/plugin-scaffolder-backend/alpha')); +{ + /* highlight-add-start */ +} +backend.add(import('@backstage/plugin-scaffolder-backend-module-github')); +{ + /* highlight-add-end */ +} + +backend.start(); +``` + +> Note: This is a simplified example of what your backend may look like, you may have more code in here then this. + +## Listing Actions A list of all registered actions can be found under `/create/actions`. For local development you should be able to reach them at 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 diff --git a/docs/getting-started/create-a-component.md b/docs/getting-started/create-a-component.md index d1718a2739..29ba99db83 100644 --- a/docs/getting-started/create-a-component.md +++ b/docs/getting-started/create-a-component.md @@ -20,6 +20,8 @@ If you're running Backstage with Node 20 or later, you'll need to pass the flag You should already have [a standalone app](./index.md). +You will also need to register the [GitHub Scaffolder Action module](../features/software-templates/builtin-actions.md#installing-action-modules) before moving forward. + ## Creating your component - Go to `create` and choose to create a website with the `Example Node.js Template`