Merge branch 'master' of https://github.com/fidelity-external-staging/backstage-backstage into issue-24719-update-feature-docs

2024-06-06 17:20:13 +01:00
parent 22dd53f42b a3c93913b1
commit 57f615b0c5
1097 changed files with 33454 additions and 6596 deletions
@@ -86,12 +86,17 @@ contains more information about the required fields.
 Once we have a `template.yaml` ready, we can then add it to the software catalog
 for use by the scaffolder.

-> Note: When you add or modify a template, you will need to refresh the location entity.
-> Otherwise, Backstage won't display the template in the available templates,
-> or it will keep showing the old template. You can refresh the location instance by
-> going into `Catalog` web page, choosing `Locations` instead of `Components`, and selecting the correct location entity.
-> From there, you can click on the refresh icon representing "Scheduled entity refresh" action.
-> Afterwards, you should see your template updated.
+:::note Note
+
+When you add or modify a template, you will need to refresh the location entity.
+Otherwise, Backstage won't display the template in the available templates,
+or it will keep showing the old template. You can refresh the location instance by
+going into `Catalog` web page, choosing `Locations` instead of `Components`, and selecting the correct
+location entity.
+From there, you can click on the refresh icon representing "Scheduled entity refresh" action.
+Afterwards, you should see your template updated.
+
+:::

 You can add the template files to the catalog through
 [static location configuration](../software-catalog/configuration.md#static-location-configuration),
@@ -1,10 +1,10 @@
 ---
-id: authorizing-parameters-steps-and-actions
-title: 'Authorizing parameters, steps and actions'
-description: How to authorize part of a template
+id: authorizing-scaffolder-template-details
+title: 'Authorizing scaffolder tasks, parameters, steps, and actions'
+description: How to authorize parts of a template and authorize scaffolder task access
 ---

-The scaffolder plugin integrates with the Backstage [permission framework](../../permissions/overview.md), which allows you to control access to certain parameters and steps in your templates based on the user executing the template.
+The scaffolder plugin integrates with the Backstage [permission framework](../../permissions/overview.md), which allows you to control access to certain parameters and steps in your templates based on the user executing the template. It also allows you to control access to scaffolder tasks.

 ### Authorizing parameters and steps

@@ -174,7 +174,64 @@ class ExamplePermissionPolicy implements PermissionPolicy {
 }
 ```

-Although the rules exported by the scaffolder are simple, combining them can help you achieve more complex cases.
+### Authorizing scaffolder tasks
+
+The scaffolder plugin also exposes permissions that can restrict access to tasks, task logs, task creation, and task cancellation. This can be useful if you want to control who has access to these areas of the scaffolder.
+
+```ts title="packages/src/backend/plugins/permissions.ts"
+/* highlight-add-start */
+import {
+  taskCancelPermission,
+  taskCreatePermission,
+  taskReadPermission,
+} from '@backstage/plugin-scaffolder-common/alpha';
+/* highlight-add-end */
+
+class ExamplePermissionPolicy implements PermissionPolicy {
+  async handle(
+    request: PolicyQuery,
+    user?: BackstageIdentityResponse,
+  ): Promise<PolicyDecision> {
+    /* highlight-add-start */
+    if (isPermission(request.permission, taskCreatePermission)) {
+      if (user?.identity.userEntityRef === 'user:default/spiderman') {
+        return {
+          result: AuthorizeResult.ALLOW,
+        };
+      }
+    }
+    if (isPermission(request.permission, taskCancelPermission)) {
+      if (user?.identity.userEntityRef === 'user:default/spiderman') {
+        return {
+          result: AuthorizeResult.ALLOW,
+        };
+      }
+    }
+    if (isPermission(request.permission, taskReadPermission)) {
+      if (user?.identity.userEntityRef === 'user:default/spiderman') {
+        return {
+          result: AuthorizeResult.ALLOW,
+        };
+      }
+    }
+    /* highlight-add-end */
+
+    return {
+      result: AuthorizeResult.DENY,
+    };
+  }
+}
+```
+
+In the provided example permission policy, we only grant the `spiderman` user permissions to perform/access the following actions/resources:
+
+- Read all scaffolder tasks and their associated events/logs.
+- Cancel any ongoing scaffolder tasks.
+- Trigger software templates, which effectively creates new scaffolder tasks.
+
+Any other user would be denied access to these actions/resources.
+
+Although the rules exported by the scaffolder are simple, combining them can help you achieve more complex use cases.

 ### Authorizing in the New Backend System

@@ -229,4 +286,8 @@ 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.
+:::note 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.
+
+:::
@@ -57,7 +57,11 @@ backend.add(import('@backstage/plugin-scaffolder-backend-module-github'));
 backend.start();
 ```

-> Note: This is a simplified example of what your backend may look like, you may have more code in here then this.
+:::note Note
+
+This is a simplified example of what your backend may look like, you may have more code in here then this.
+
+:::

 ## Listing Actions

@@ -12,7 +12,11 @@ This is done in your `app-config.yaml` by adding
 [Backstage integrations](https://backstage.io/docs/integrations/) for the
 appropriate source code repository for your organization.

-> Note: Integrations may already be set up as part of your `app-config.yaml`.
+:::note Note
+
+Integrations may already be set up as part of your `app-config.yaml`.
+
+:::

 The next step is to [add templates](http://backstage.io/docs/features/software-templates/adding-templates)
 to your Backstage app.
@@ -20,10 +20,14 @@ locations like GitHub or GitLab.
 > Be sure to have covered
 > [Getting Started with Backstage](../../getting-started) before proceeding.

-> Note: if you're running Backstage with Node 20 or later, you'll need to pass the flag `--no-node-snapshot` to Node in order to
-> use the templates feature.
-> One way to do this is to specify the `NODE_OPTIONS` environment variable before starting Backstage:
-> `export NODE_OPTIONS=--no-node-snapshot`
+:::note Note
+
+If you're running Backstage with Node 20 or later, you'll need to pass the flag `--no-node-snapshot` to Node in order to
+use the templates feature.
+One way to do this is to specify the `NODE_OPTIONS` environment variable before starting Backstage:
+`export NODE_OPTIONS=--no-node-snapshot`
+
+:::

 The Software Templates are available under `/create`. For local development you
 should be able to reach them at `http://localhost:3000/create`.
@@ -5,7 +5,11 @@ title: 'Migrating to react-jsonschema-form@v5'
 description: Docs on migrating to `react-jsonschema-form`@v5 and the new designs
 ---

-> Note: If you were previously using the `/alpha` imports to test out the `scaffolder/next` work, those imports have been promoted to the default exports from the respective packages. You should just have to remove the `/alpha` from the import path, and remove the `Next` from the import name. `NextScaffolderPage` -> `ScaffolderPage`, `createNextScaffolderFieldExtension` -> `createScaffolderFieldExtension` etc.
+:::note Note
+
+If you were previously using the `/alpha` imports to test out the `scaffolder/next` work, those imports have been promoted to the default exports from the respective packages. You should just have to remove the `/alpha` from the import path, and remove the `Next` from the import name. `NextScaffolderPage` -> `ScaffolderPage`, `createNextScaffolderFieldExtension` -> `createScaffolderFieldExtension` etc.
+
+:::

 ## What's `react-jsonschema-form`?

@@ -8,10 +8,14 @@ If you want to extend the functionality of the Scaffolder, you can do so
 by writing custom actions which can be used alongside our
 [built-in actions](./builtin-actions.md).

-> Note: When adding custom actions, the actions array will **replace the
-> built-in actions too**. Meaning, you will no longer be able to use them.
-> If you want to continue using the builtin actions, include them in the actions
-> array when registering your custom actions, as seen below.
+:::note Note
+
+When adding custom actions, the actions array will **replace the
+built-in actions too**. Meaning, you will no longer be able to use them.
+If you want to continue using the builtin actions, include them in the actions
+array when registering your custom actions, as seen below.
+
+:::

 ## Streamlining Custom Action Creation with Backstage CLI

@@ -226,7 +230,7 @@ const scaffolderModuleCustomExtensions = createBackendModule({
      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
+        scaffolder.addActions(createNewFileAction()); // just an example
      },
    });
  },