Updated with new backend system examples

Signed-off-by: Andre Wanlin <awanlin@spotify.com>

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<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.

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';

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