@backstage/plugin-scaffolder-backend 1.10.0-next.1 → 1.10.0-next.2

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # @backstage/plugin-scaffolder-backend
 
+## 1.10.0-next.2
+
+### Patch Changes
+
+- 2fadff2a25: Change scaffolder task actions to include markdown to demonstrate the new `ActionsPage` markdown feature.
+- b44eb68bcb: This patch adds changes to provide examples alongside scaffolder task actions.
+
+  The `createTemplateAction` function now takes a list of examples e.g.
+
+  ```typescript
+  const actionExamples = [
+    {
+      description: 'Example 1',
+      example: yaml.stringify({
+        steps: [
+          {
+            action: 'test:action',
+            id: 'test',
+            input: {
+              input1: 'value',
+            },
+          },
+        ],
+      }),
+    },
+  ];
+
+  export function createTestAction() {
+    return createTemplateAction({
+        id: 'test:action',
+        examples: [
+            {
+                description: 'Example 1',
+                examples: actionExamples
+            }
+        ],
+        ...,
+    });
+  ```
+
+  These examples can be retrieved later from the api.
+
+  ```bash
+  curl http://localhost:7007/api/scaffolder/v2/actions
+  ```
+
+  ```json
+  [
+    {
+      "id": "test:action",
+      "examples": [
+        {
+          "description": "Example 1",
+          "example": "steps:\n  - action: test:action\n    id: test\n    input:\n      input1: value\n"
+        }
+      ],
+      "schema": {
+        "input": {
+          "type": "object",
+          "properties": {
+            "input1": {
+              "title": "Input 1",
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  ]
+  ```
+
+- 8e06f3cf00: Switched imports of `loggerToWinstonLogger` to `@backstage/backend-common`.
+- Updated dependencies
+  - @backstage/backend-plugin-api@0.3.0-next.1
+  - @backstage/backend-common@0.18.0-next.1
+  - @backstage/backend-tasks@0.4.1-next.1
+  - @backstage/catalog-client@1.3.0-next.2
+  - @backstage/plugin-catalog-backend@1.7.0-next.2
+  - @backstage/plugin-catalog-node@1.3.1-next.2
+  - @backstage/plugin-auth-node@0.2.9-next.1
+  - @backstage/catalog-model@1.1.5-next.1
+  - @backstage/config@1.0.6-next.0
+  - @backstage/errors@1.1.4
+  - @backstage/integration@1.4.2-next.0
+  - @backstage/types@1.0.2
+  - @backstage/plugin-scaffolder-common@1.2.4-next.1
+
 ## 1.10.0-next.1
 
 ### Minor Changes

package/alpha/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/plugin-scaffolder-backend",
-  "version": "1.10.0-next.1",
+  "version": "1.10.0-next.2",
   "main": "../dist/index.cjs.js",
   "types": "../dist/index.alpha.d.ts"
 }

package/dist/index.alpha.d.ts

@@ -1063,6 +1063,10 @@ export declare class TaskWorker {
 export declare type TemplateAction<Input extends JsonObject> = {
     id: string;
     description?: string;
+    examples?: {
+        description: string;
+        example: string;
+    }[];
     supportsDryRun?: boolean;
     schema?: {
         input?: Schema;

package/dist/index.beta.d.ts

@@ -1045,6 +1045,10 @@ export declare class TaskWorker {
 export declare type TemplateAction<Input extends JsonObject> = {
     id: string;
     description?: string;
+    examples?: {
+        description: string;
+        example: string;
+    }[];
     supportsDryRun?: boolean;
     schema?: {
         input?: Schema;

package/dist/index.cjs.js

@@ -4,8 +4,8 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 var errors = require('@backstage/errors');
 var catalogModel = require('@backstage/catalog-model');
-var fs = require('fs-extra');
 var yaml = require('yaml');
+var fs = require('fs-extra');
 var backendCommon = require('@backstage/backend-common');
 var integration = require('@backstage/integration');
 var path = require('path');
@@ -62,8 +62,9 @@ function _interopNamespace(e) {
   return Object.freeze(n);
 }
 
-var fs__default = /*#__PURE__*/_interopDefaultLegacy(fs);
+var yaml__default = /*#__PURE__*/_interopDefaultLegacy(yaml);
 var yaml__namespace = /*#__PURE__*/_interopNamespace(yaml);
+var fs__default = /*#__PURE__*/_interopDefaultLegacy(fs);
 var path__default = /*#__PURE__*/_interopDefaultLegacy(path);
 var globby__default = /*#__PURE__*/_interopDefaultLegacy(globby);
 var fetch__default = /*#__PURE__*/_interopDefaultLegacy(fetch);
@@ -81,11 +82,30 @@ const createTemplateAction = (templateAction) => {
   return templateAction;
 };
 
+const id$2 = "catalog:register";
+const examples$2 = [
+  {
+    description: "Register with the catalog",
+    example: yaml__default["default"].stringify({
+      steps: [
+        {
+          action: id$2,
+          id: "register-with-catalog",
+          name: "Register with the catalog",
+          input: {
+            catalogInfoUrl: "http://github.com/backstage/backstage/blob/master/catalog-info.yaml"
+          }
+        }
+      ]
+    })
+  }
+];
 function createCatalogRegisterAction(options) {
   const { catalogClient, integrations } = options;
   return createTemplateAction({
-    id: "catalog:register",
+    id: id$2,
     description: "Registers entities from a catalog descriptor file in the workspace into the software catalog.",
+    examples: examples$2,
     schema: {
       input: {
         oneOf: [
@@ -203,10 +223,41 @@ function createCatalogRegisterAction(options) {
   });
 }
 
+const id$1 = "catalog:write";
+const examples$1 = [
+  {
+    description: "Write a catalog yaml file",
+    example: yaml__namespace.stringify({
+      steps: [
+        {
+          action: id$1,
+          id: "create-catalog-info-file",
+          name: "Create catalog file",
+          input: {
+            entity: {
+              apiVersion: "backstage.io/v1alpha1",
+              kind: "Component",
+              metadata: {
+                name: "test",
+                annotations: {}
+              },
+              spec: {
+                type: "service",
+                lifecycle: "production",
+                owner: "default/owner"
+              }
+            }
+          }
+        }
+      ]
+    })
+  }
+];
 function createCatalogWriteAction() {
   return createTemplateAction({
-    id: "catalog:write",
+    id: id$1,
     description: "Writes the catalog-info.yaml for your template",
+    examples: examples$1,
     schema: {
       input: {
         type: "object",
@@ -237,10 +288,44 @@ function createCatalogWriteAction() {
   });
 }
 
+const id = "debug:log";
+const examples = [
+  {
+    description: "Write a debug message",
+    example: yaml__default["default"].stringify({
+      steps: [
+        {
+          action: id,
+          id: "write-debug-line",
+          name: 'Write "Hello Backstage!" log line',
+          input: {
+            message: "Hello Backstage!"
+          }
+        }
+      ]
+    })
+  },
+  {
+    description: "List the workspace directory",
+    example: yaml__default["default"].stringify({
+      steps: [
+        {
+          action: id,
+          id: "write-workspace-directory",
+          name: "List the workspace directory",
+          input: {
+            listWorkspace: true
+          }
+        }
+      ]
+    })
+  }
+];
 function createDebugLogAction() {
   return createTemplateAction({
-    id: "debug:log",
+    id,
     description: "Writes a message into the log or lists all files in the workspace.",
+    examples,
     schema: {
       input: {
         type: "object",
@@ -327,7 +412,7 @@ function createFetchPlainAction(options) {
   const { reader, integrations } = options;
   return createTemplateAction({
     id: "fetch:plain",
-    description: "Downloads content and places it in the workspace, or optionally in a subdirectory specified by the 'targetPath' input option.",
+    description: "Downloads content and places it in the workspace, or optionally in a subdirectory specified by the `targetPath` input option.",
     schema: {
       input: {
         type: "object",
@@ -512,7 +597,7 @@ function createFetchTemplateAction(options) {
   } = options;
   return createTemplateAction({
     id: "fetch:template",
-    description: "Downloads a skeleton, templates variables into file and directory names and content, and places the result in the workspace, or optionally in a subdirectory specified by the 'targetPath' input option.",
+    description: "Downloads a skeleton, templates variables into file and directory names and content, and places the result in the workspace, or optionally in a subdirectory specified by the `targetPath` input option.",
     schema: {
       input: {
         type: "object",
@@ -1007,6 +1092,13 @@ const enableBranchProtectionOnDefaultRepoBranch = async ({
     try {
       await client.rest.repos.updateBranchProtection({
         mediaType: {
+          /**
+           * 👇 we need this preview because allowing a custom
+           * reviewer count on branch protection is a preview
+           * feature
+           *
+           * More here: https://docs.github.com/en/rest/overview/api-previews#require-multiple-approving-reviews
+           */
           previews: ["luke-cage-preview"]
         },
         owner,
@@ -1056,6 +1148,7 @@ async function getOctokitOptions(options) {
   const { integrations, credentialsProvider, repoUrl, token } = options;
   const { owner, repo, host } = parseRepoUrl(repoUrl, integrations);
   const requestOptions = {
+    // set timeout to 60 seconds
     timeout: DEFAULT_TIMEOUT_MS
   };
   if (!owner) {
@@ -3155,6 +3248,8 @@ async function serializeDirectoryContents(sourcePath, options) {
     dot: true,
     gitignore: options == null ? void 0 : options.gitignore,
     followSymbolicLinks: false,
+    // In order to pick up 'broken' symlinks, we oxymoronically request files AND folders yet we filter out folders
+    // This is because broken symlinks aren't classed as files so we need to glob everything
     onlyFiles: false,
     objectMode: true,
     stats: true
@@ -3352,7 +3447,16 @@ const createPublishGithubPullRequestAction = ({
         directoryContents.map((file) => [
           targetPath ? path__default["default"].posix.join(targetPath, file.path) : file.path,
           {
+            // See the properties of tree items
+            // in https://docs.github.com/en/rest/reference/git#trees
             mode: determineFileMode(file),
+            // Always use base64 encoding where possible to avoid doubling a binary file in size
+            // due to interpreting a binary file as utf-8 and sending github
+            // the utf-8 encoded content. Symlinks are kept as utf-8 to avoid them
+            // being formatted as a series of scrambled characters
+            //
+            // For example, the original gradle-wrapper.jar is 57.8k in https://github.com/kennethzfeng/pull-request-test/pull/5/files.
+            // Its size could be doubled to 98.3K (See https://github.com/kennethzfeng/pull-request-test/pull/4/files)
             encoding: determineFileEncoding(file),
             content: file.content.toString(determineFileEncoding(file))
           }
@@ -3589,6 +3693,7 @@ const createPublishGitlabMergeRequestAction = (options) => {
             title: "Repository Location",
             description: `Accepts the format 'gitlab.com/group_name/project_name' where 'project_name' is the repository name and 'group_name' is a group or username`
           },
+          /** @deprecated projectID is passed as query parameters in the repoUrl */
           projectid: {
             type: "string",
             title: "projectid",
@@ -3990,6 +4095,7 @@ class DatabaseTaskStore {
       const updateCount = await tx("tasks").where({ id: task.id, status: "open" }).update({
         status: "processing",
         last_heartbeat_at: this.db.fn.now(),
+        // remove the secrets when moving moving to processing state.
         secrets: null
       });
       if (updateCount < 1) {
@@ -4140,6 +4246,7 @@ class DatabaseTaskStore {
 }
 
 class TaskManager {
+  // Runs heartbeat internally
   constructor(task, storage, logger) {
     this.task = task;
     this.storage = storage;
@@ -4223,6 +4330,9 @@ class StorageTaskBroker {
     }
     return await this.storage.list({ createdBy: options == null ? void 0 : options.createdBy });
   }
+  /**
+   * {@inheritdoc TaskBroker.claim}
+   */
   async claim() {
     for (; ; ) {
       const pendingTask = await this.storage.claimTask();
@@ -4241,6 +4351,9 @@ class StorageTaskBroker {
       await this.waitForDispatch();
     }
   }
+  /**
+   * {@inheritdoc TaskBroker.dispatch}
+   */
   async dispatch(options) {
     const taskRow = await this.storage.createTask(options);
     this.signalDispatch();
@@ -4248,9 +4361,15 @@ class StorageTaskBroker {
       taskId: taskRow.taskId
     };
   }
+  /**
+   * {@inheritdoc TaskBroker.get}
+   */
   async get(taskId) {
     return this.storage.getTask(taskId);
   }
+  /**
+   * {@inheritdoc TaskBroker.event$}
+   */
   event$(options) {
     return new ObservableImpl__default["default"]((observer) => {
       const { taskId } = options;
@@ -4272,6 +4391,9 @@ class StorageTaskBroker {
       };
     });
   }
+  /**
+   * {@inheritdoc TaskBroker.vacuumTasks}
+   */
   async vacuumTasks(options) {
     const { tasks } = await this.storage.listStaleTasks(options);
     await Promise.all(
@@ -4441,6 +4563,10 @@ class NunjucksWorkflowRunner {
     );
     const { integrations } = this.options;
     const renderTemplate = await SecureTemplater.loadRenderer({
+      // TODO(blam): let's work out how we can deprecate this.
+      // We shouldn't really need to be exposing these now we can deal with
+      // objects in the params block.
+      // Maybe we can expose a new RepoUrlPicker with secrets for V3 that provides an object already.
       parseRepoUrl(url) {
         return parseRepoUrl(url, integrations);
       },
@@ -4693,6 +4819,7 @@ class TaskWorker {
       workingDirectory,
       additionalTemplateFilters,
       concurrentTasksLimit = 10,
+      // from 1 to Infinity
       additionalTemplateGlobals
     } = options;
     const workflowRunner = new NunjucksWorkflowRunner({
@@ -4809,6 +4936,7 @@ function createDryRunner(options) {
           }
         },
         secrets: input.secrets,
+        // No need to update this at the end of the run, so just hard-code it
         done: false,
         isDryRun: true,
         getWorkspaceName: async () => `dry-run-${dryRunId}`,
@@ -4963,6 +5091,7 @@ async function createRouter(options) {
       await scheduler.scheduleTask({
         id: "close_stale_tasks",
         frequency: { cron: "*/5 * * * *" },
+        // every 5 minutes, also supports Duration
         timeout: { minutes: 15 },
         fn: async () => {
           const { tasks } = await databaseTaskStore.listStaleTasks({
@@ -5051,6 +5180,7 @@ async function createRouter(options) {
       return {
         id: action.id,
         description: action.description,
+        examples: action.examples,
         schema: action.schema
       };
     });
@@ -5409,7 +5539,7 @@ const scaffolderPlugin = backendPluginApi.createBackendPlugin({
           taskWorkers,
           additionalTemplateGlobals
         } = options;
-        const log = backendPluginApi.loggerToWinstonLogger(logger);
+        const log = backendCommon.loggerToWinstonLogger(logger);
         const actions = options.actions || [
           ...actionsExtensions.actions,
           ...createBuiltinActions({