From 7e182e644c11dac289b99ed503ea9248bd2aa485 Mon Sep 17 00:00:00 2001 From: Andre Wanlin Date: Sat, 23 Mar 2024 22:25:39 +0100 Subject: [PATCH 1/5] Include GitHub scaffolder actions Signed-off-by: Andre Wanlin --- .changeset/seven-kangaroos-sit.md | 5 +++ .../software-templates/builtin-actions.md | 42 ++++++++++++++++++- packages/create-app/src/lib/versions.ts | 3 ++ .../packages/backend/package.json.hbs | 1 + .../default-app/packages/backend/src/index.ts | 7 +++- 5 files changed, 55 insertions(+), 3 deletions(-) create mode 100644 .changeset/seven-kangaroos-sit.md diff --git a/.changeset/seven-kangaroos-sit.md b/.changeset/seven-kangaroos-sit.md new file mode 100644 index 0000000000..c4d2fb5b22 --- /dev/null +++ b/.changeset/seven-kangaroos-sit.md @@ -0,0 +1,5 @@ +--- +'@backstage/create-app': patch +--- + +Include `@backstage/plugin-scaffolder-backend-module-github` out of the box diff --git a/docs/features/software-templates/builtin-actions.md b/docs/features/software-templates/builtin-actions.md index 1b3a53b5d9..a40caf4c42 100644 --- a/docs/features/software-templates/builtin-actions.md +++ b/docs/features/software-templates/builtin-actions.md @@ -8,8 +8,46 @@ 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 + +The GitHub module is included out of the box, but several other modules are available: + +- 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` +- GitLab: `@backstage/plugin-scaffolder-backend-module-gitlab` + +Here's how to add an action module, this is a simplified backend 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-azure')); +{ + /* highlight-add-end */ +} + +backend.start(); +``` + +## 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/packages/create-app/src/lib/versions.ts b/packages/create-app/src/lib/versions.ts index 76f3c37f78..288135c5db 100644 --- a/packages/create-app/src/lib/versions.ts +++ b/packages/create-app/src/lib/versions.ts @@ -74,6 +74,7 @@ import { version as pluginProxyBackend } from '../../../../plugins/proxy-backend import { version as pluginRollbarBackend } from '../../../../plugins/rollbar-backend/package.json'; import { version as pluginScaffolder } from '../../../../plugins/scaffolder/package.json'; import { version as pluginScaffolderBackend } from '../../../../plugins/scaffolder-backend/package.json'; +import { version as pluginScaffolderBackendModuleGithub } from '../../../../plugins/scaffolder-backend-module-github/package.json'; import { version as pluginSearch } from '../../../../plugins/search/package.json'; import { version as pluginSearchReact } from '../../../../plugins/search-react/package.json'; import { version as pluginSearchBackend } from '../../../../plugins/search-backend/package.json'; @@ -134,6 +135,8 @@ export const packageVersions = { '@backstage/plugin-rollbar-backend': pluginRollbarBackend, '@backstage/plugin-scaffolder': pluginScaffolder, '@backstage/plugin-scaffolder-backend': pluginScaffolderBackend, + '@backstage/plugin-scaffolder-backend-module-github': + pluginScaffolderBackendModuleGithub, '@backstage/plugin-search': pluginSearch, '@backstage/plugin-search-react': pluginSearchReact, '@backstage/plugin-search-backend': pluginSearchBackend, diff --git a/packages/create-app/templates/default-app/packages/backend/package.json.hbs b/packages/create-app/templates/default-app/packages/backend/package.json.hbs index 93228e5c8f..cbf2a0389e 100644 --- a/packages/create-app/templates/default-app/packages/backend/package.json.hbs +++ b/packages/create-app/templates/default-app/packages/backend/package.json.hbs @@ -33,6 +33,7 @@ "@backstage/plugin-permission-node": "^{{version '@backstage/plugin-permission-node'}}", "@backstage/plugin-proxy-backend": "^{{version '@backstage/plugin-proxy-backend'}}", "@backstage/plugin-scaffolder-backend": "^{{version '@backstage/plugin-scaffolder-backend'}}", + "@backstage/plugin-scaffolder-backend-module-github": "^{{version '@backstage/plugin-scaffolder-backend-module-github'}}", "@backstage/plugin-search-backend": "^{{version '@backstage/plugin-search-backend'}}", "@backstage/plugin-search-backend-module-catalog": "^{{version '@backstage/plugin-search-backend-module-catalog'}}", "@backstage/plugin-search-backend-module-techdocs": "^{{version '@backstage/plugin-search-backend-module-techdocs'}}", diff --git a/packages/create-app/templates/default-app/packages/backend/src/index.ts b/packages/create-app/templates/default-app/packages/backend/src/index.ts index 44fde697ec..c93dba382a 100644 --- a/packages/create-app/templates/default-app/packages/backend/src/index.ts +++ b/packages/create-app/templates/default-app/packages/backend/src/index.ts @@ -12,7 +12,6 @@ const backend = createBackend(); backend.add(import('@backstage/plugin-app-backend/alpha')); backend.add(import('@backstage/plugin-proxy-backend/alpha')); -backend.add(import('@backstage/plugin-scaffolder-backend/alpha')); backend.add(import('@backstage/plugin-techdocs-backend/alpha')); // auth plugin @@ -33,6 +32,12 @@ backend.add( import('@backstage/plugin-permission-backend-module-allow-all-policy'), ); +// scaffolder plugin +backend.add(import('@backstage/plugin-scaffolder-backend/alpha')); +// See: https://backstage.io/docs/features/software-templates/builtin-actions#action-modules +// If you don't use GitHub, feel free to remove this +backend.add(import('@backstage/plugin-scaffolder-backend-module-github')); + // search plugin backend.add(import('@backstage/plugin-search-backend/alpha')); backend.add(import('@backstage/plugin-search-backend-module-catalog/alpha')); From 8c8d2c81dc073c747d6408009f20a7e7885140b2 Mon Sep 17 00:00:00 2001 From: Andre Wanlin Date: Sat, 6 Apr 2024 18:54:51 -0500 Subject: [PATCH 2/5] Reverted create-app changes Signed-off-by: Andre Wanlin --- .changeset/seven-kangaroos-sit.md | 5 ----- packages/create-app/src/lib/versions.ts | 3 --- .../default-app/packages/backend/package.json.hbs | 1 - .../templates/default-app/packages/backend/src/index.ts | 7 +------ 4 files changed, 1 insertion(+), 15 deletions(-) delete mode 100644 .changeset/seven-kangaroos-sit.md diff --git a/.changeset/seven-kangaroos-sit.md b/.changeset/seven-kangaroos-sit.md deleted file mode 100644 index c4d2fb5b22..0000000000 --- a/.changeset/seven-kangaroos-sit.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/create-app': patch ---- - -Include `@backstage/plugin-scaffolder-backend-module-github` out of the box diff --git a/packages/create-app/src/lib/versions.ts b/packages/create-app/src/lib/versions.ts index 288135c5db..76f3c37f78 100644 --- a/packages/create-app/src/lib/versions.ts +++ b/packages/create-app/src/lib/versions.ts @@ -74,7 +74,6 @@ import { version as pluginProxyBackend } from '../../../../plugins/proxy-backend import { version as pluginRollbarBackend } from '../../../../plugins/rollbar-backend/package.json'; import { version as pluginScaffolder } from '../../../../plugins/scaffolder/package.json'; import { version as pluginScaffolderBackend } from '../../../../plugins/scaffolder-backend/package.json'; -import { version as pluginScaffolderBackendModuleGithub } from '../../../../plugins/scaffolder-backend-module-github/package.json'; import { version as pluginSearch } from '../../../../plugins/search/package.json'; import { version as pluginSearchReact } from '../../../../plugins/search-react/package.json'; import { version as pluginSearchBackend } from '../../../../plugins/search-backend/package.json'; @@ -135,8 +134,6 @@ export const packageVersions = { '@backstage/plugin-rollbar-backend': pluginRollbarBackend, '@backstage/plugin-scaffolder': pluginScaffolder, '@backstage/plugin-scaffolder-backend': pluginScaffolderBackend, - '@backstage/plugin-scaffolder-backend-module-github': - pluginScaffolderBackendModuleGithub, '@backstage/plugin-search': pluginSearch, '@backstage/plugin-search-react': pluginSearchReact, '@backstage/plugin-search-backend': pluginSearchBackend, diff --git a/packages/create-app/templates/default-app/packages/backend/package.json.hbs b/packages/create-app/templates/default-app/packages/backend/package.json.hbs index cbf2a0389e..93228e5c8f 100644 --- a/packages/create-app/templates/default-app/packages/backend/package.json.hbs +++ b/packages/create-app/templates/default-app/packages/backend/package.json.hbs @@ -33,7 +33,6 @@ "@backstage/plugin-permission-node": "^{{version '@backstage/plugin-permission-node'}}", "@backstage/plugin-proxy-backend": "^{{version '@backstage/plugin-proxy-backend'}}", "@backstage/plugin-scaffolder-backend": "^{{version '@backstage/plugin-scaffolder-backend'}}", - "@backstage/plugin-scaffolder-backend-module-github": "^{{version '@backstage/plugin-scaffolder-backend-module-github'}}", "@backstage/plugin-search-backend": "^{{version '@backstage/plugin-search-backend'}}", "@backstage/plugin-search-backend-module-catalog": "^{{version '@backstage/plugin-search-backend-module-catalog'}}", "@backstage/plugin-search-backend-module-techdocs": "^{{version '@backstage/plugin-search-backend-module-techdocs'}}", diff --git a/packages/create-app/templates/default-app/packages/backend/src/index.ts b/packages/create-app/templates/default-app/packages/backend/src/index.ts index c93dba382a..44fde697ec 100644 --- a/packages/create-app/templates/default-app/packages/backend/src/index.ts +++ b/packages/create-app/templates/default-app/packages/backend/src/index.ts @@ -12,6 +12,7 @@ const backend = createBackend(); backend.add(import('@backstage/plugin-app-backend/alpha')); backend.add(import('@backstage/plugin-proxy-backend/alpha')); +backend.add(import('@backstage/plugin-scaffolder-backend/alpha')); backend.add(import('@backstage/plugin-techdocs-backend/alpha')); // auth plugin @@ -32,12 +33,6 @@ backend.add( import('@backstage/plugin-permission-backend-module-allow-all-policy'), ); -// scaffolder plugin -backend.add(import('@backstage/plugin-scaffolder-backend/alpha')); -// See: https://backstage.io/docs/features/software-templates/builtin-actions#action-modules -// If you don't use GitHub, feel free to remove this -backend.add(import('@backstage/plugin-scaffolder-backend-module-github')); - // search plugin backend.add(import('@backstage/plugin-search-backend/alpha')); backend.add(import('@backstage/plugin-search-backend-module-catalog/alpha')); From 9d287aa7d372df7711df252b1ea04b3f261c05a5 Mon Sep 17 00:00:00 2001 From: Andre Wanlin Date: Sat, 6 Apr 2024 19:14:09 -0500 Subject: [PATCH 3/5] Updated with new backend system examples Signed-off-by: Andre Wanlin --- ...uthorizing-parameters-steps-and-actions.md | 55 +++++++++++++++++++ .../software-templates/builtin-actions.md | 8 ++- .../writing-custom-actions.md | 38 ++++++++++++- 3 files changed, 97 insertions(+), 4 deletions(-) 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 From 90250a7a7708d0eeef38682bbf9942419c3f6ad2 Mon Sep 17 00:00:00 2001 From: Andre Wanlin Date: Sat, 6 Apr 2024 19:17:44 -0500 Subject: [PATCH 4/5] Updated create a component Signed-off-by: Andre Wanlin --- docs/getting-started/create-a-component.md | 2 ++ 1 file changed, 2 insertions(+) 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` From 8dd44ed4d79361135781532565b9650cb8b98b81 Mon Sep 17 00:00:00 2001 From: Andre Wanlin Date: Mon, 8 Apr 2024 16:11:15 -0500 Subject: [PATCH 5/5] Corrected example Signed-off-by: Andre Wanlin --- .../software-templates/builtin-actions.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/docs/features/software-templates/builtin-actions.md b/docs/features/software-templates/builtin-actions.md index 53819f67ce..94b2d2298b 100644 --- a/docs/features/software-templates/builtin-actions.md +++ b/docs/features/software-templates/builtin-actions.md @@ -17,13 +17,21 @@ There are also several modules available for various SCM tools: - 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, this is a simplified new backend system for example purposes: +Here's how to add an action module, first you need to run this command: -```ts title="/packages/backend/src/index.ts +```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(); @@ -41,7 +49,7 @@ backend.add(import('@backstage/plugin-scaffolder-backend/alpha')); { /* highlight-add-start */ } -backend.add(import('@backstage/plugin-scaffolder-backend-module-azure')); +backend.add(import('@backstage/plugin-scaffolder-backend-module-github')); { /* highlight-add-end */ } @@ -49,6 +57,8 @@ backend.add(import('@backstage/plugin-scaffolder-backend-module-azure')); 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