Merge pull request #23823 from awanlin/topic/include-github-scaffolder-actions

Updated Software Template docs with New Backend System examples
2024-04-09 10:25:42 +02:00
parent 305fb73d1e 8dd44ed4d7
commit f3fc0e2b52
4 changed files with 146 additions and 3 deletions
@@ -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<PolicyDecision> {
+    // 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.
@@ -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
@@ -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
@@ -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`