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

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$3 = "catalog:register";
+const examples$3 = [
+  {
+    description: "Register with the catalog",
+    example: yaml__default["default"].stringify({
+      steps: [
+        {
+          action: id$3,
+          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$3,
     description: "Registers entities from a catalog descriptor file in the workspace into the software catalog.",
+    examples: examples$3,
     schema: {
       input: {
         oneOf: [
@@ -203,10 +223,41 @@ function createCatalogRegisterAction(options) {
   });
 }
 
+const id$2 = "catalog:write";
+const examples$2 = [
+  {
+    description: "Write a catalog yaml file",
+    example: yaml__namespace.stringify({
+      steps: [
+        {
+          action: id$2,
+          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$2,
     description: "Writes the catalog-info.yaml for your template",
+    examples: examples$2,
     schema: {
       input: {
         type: "object",
@@ -237,10 +288,114 @@ function createCatalogWriteAction() {
   });
 }
 
+const id$1 = "catalog:fetch";
+const examples$1 = [
+  {
+    description: "Fetch entity by reference",
+    example: yaml__default["default"].stringify({
+      steps: [
+        {
+          action: id$1,
+          id: "fetch",
+          name: "Fetch catalog entity",
+          input: {
+            entityRef: "component:default/name"
+          }
+        }
+      ]
+    })
+  }
+];
+function createFetchCatalogEntityAction(options) {
+  const { catalogClient } = options;
+  return createTemplateAction({
+    id: id$1,
+    description: "Returns entity from the catalog by entity reference",
+    examples: examples$1,
+    schema: {
+      input: {
+        required: ["entityRef"],
+        type: "object",
+        properties: {
+          entityRef: {
+            type: "string",
+            title: "Entity reference",
+            description: "Entity reference of the entity to get"
+          },
+          optional: {
+            title: "Optional",
+            description: "Permit the entity to optionally exist. Default: false",
+            type: "boolean"
+          }
+        }
+      },
+      output: {
+        type: "object",
+        properties: {
+          entity: {
+            title: "Entity found by the entity reference",
+            type: "object",
+            description: "Object containing same values used in the Entity schema."
+          }
+        }
+      }
+    },
+    async handler(ctx) {
+      var _a;
+      const { entityRef, optional } = ctx.input;
+      let entity;
+      try {
+        entity = await catalogClient.getEntityByRef(entityRef, {
+          token: (_a = ctx.secrets) == null ? void 0 : _a.backstageToken
+        });
+      } catch (e) {
+        if (!optional) {
+          throw e;
+        }
+      }
+      ctx.output("entity", entity != null ? entity : null);
+    }
+  });
+}
+
+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 +482,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 +667,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",
@@ -996,17 +1151,27 @@ const enableBranchProtectionOnDefaultRepoBranch = async ({
   logger,
   requireCodeOwnerReviews,
   bypassPullRequestAllowances,
+  requiredApprovingReviewCount,
+  restrictions,
   requiredStatusCheckContexts = [],
   requireBranchesToBeUpToDate = true,
   requiredConversationResolution = false,
   defaultBranch = "master",
   enforceAdmins = true,
-  dismissStaleReviews = false
+  dismissStaleReviews = false,
+  requiredCommitSigning = false
 }) => {
   const tryOnce = 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,
@@ -1016,16 +1181,23 @@ const enableBranchProtectionOnDefaultRepoBranch = async ({
           strict: requireBranchesToBeUpToDate,
           contexts: requiredStatusCheckContexts
         },
-        restrictions: null,
+        restrictions: restrictions != null ? restrictions : null,
         enforce_admins: enforceAdmins,
         required_pull_request_reviews: {
-          required_approving_review_count: 1,
+          required_approving_review_count: requiredApprovingReviewCount,
           require_code_owner_reviews: requireCodeOwnerReviews,
           bypass_pull_request_allowances: bypassPullRequestAllowances,
           dismiss_stale_reviews: dismissStaleReviews
         },
         required_conversation_resolution: requiredConversationResolution
       });
+      if (requiredCommitSigning) {
+        await client.rest.repos.createCommitSignatureProtection({
+          owner,
+          repo: repoName,
+          branch: defaultBranch
+        });
+      }
     } catch (e) {
       errors.assertError(e);
       if (e.message.includes(
@@ -1056,6 +1228,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) {
@@ -1200,7 +1373,7 @@ async function createGithubRepoWithCollaboratorsAndTopics(client, repo, owner, r
   }
   return newRepo;
 }
-async function initRepoPushAndProtect(remoteUrl, password, workspacePath, sourcePath, defaultBranch, protectDefaultBranch, protectEnforceAdmins, owner, client, repo, requireCodeOwnerReviews, bypassPullRequestAllowances, requiredStatusCheckContexts, requireBranchesToBeUpToDate, requiredConversationResolution, config, logger, gitCommitMessage, gitAuthorName, gitAuthorEmail, dismissStaleReviews) {
+async function initRepoPushAndProtect(remoteUrl, password, workspacePath, sourcePath, defaultBranch, protectDefaultBranch, protectEnforceAdmins, owner, client, repo, requireCodeOwnerReviews, bypassPullRequestAllowances, requiredApprovingReviewCount, restrictions, requiredStatusCheckContexts, requireBranchesToBeUpToDate, requiredConversationResolution, config, logger, gitCommitMessage, gitAuthorName, gitAuthorEmail, dismissStaleReviews, requiredCommitSigning) {
   const gitAuthorInfo = {
     name: gitAuthorName ? gitAuthorName : config.getOptionalString("scaffolder.defaultAuthor.name"),
     email: gitAuthorEmail ? gitAuthorEmail : config.getOptionalString("scaffolder.defaultAuthor.email")
@@ -1227,12 +1400,15 @@ async function initRepoPushAndProtect(remoteUrl, password, workspacePath, source
         logger,
         defaultBranch,
         bypassPullRequestAllowances,
+        requiredApprovingReviewCount,
+        restrictions,
         requireCodeOwnerReviews,
         requiredStatusCheckContexts,
         requireBranchesToBeUpToDate,
         requiredConversationResolution,
         enforceAdmins: protectEnforceAdmins,
-        dismissStaleReviews
+        dismissStaleReviews,
+        requiredCommitSigning
       });
     } catch (e) {
       errors.assertError(e);
@@ -1590,6 +1766,42 @@ const sourcePath = {
   description: "Path within the workspace that will be used as the repository root. If omitted, the entire workspace will be published as the repository.",
   type: "string"
 };
+const requiredApprovingReviewCount = {
+  title: "Required approving review count",
+  type: "number",
+  description: `Specify the number of reviewers required to approve pull requests. Use a number between 1 and 6 or 0 to not require reviewers. Defaults to 1.`
+};
+const restrictions = {
+  title: "Restrict who can push to the protected branch",
+  description: "Restrict who can push to the protected branch. User, app, and team restrictions are only available for organization-owned repositories.",
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    apps: {
+      type: "array",
+      items: {
+        type: "string"
+      }
+    },
+    users: {
+      type: "array",
+      items: {
+        type: "string"
+      }
+    },
+    teams: {
+      type: "array",
+      items: {
+        type: "string"
+      }
+    }
+  }
+};
+const requiredCommitSigning = {
+  title: "Require commit signing",
+  type: "boolean",
+  description: `Require commit signing so that you must sign commits on this branch.`
+};
 
 const remoteUrl = {
   title: "A URL to the repository with the provider",
@@ -1616,6 +1828,8 @@ function createGithubRepoCreateAction(options) {
           access: access,
           requireCodeOwnerReviews: requireCodeOwnerReviews,
           bypassPullRequestAllowances: bypassPullRequestAllowances,
+          requiredApprovingReviewCount: requiredApprovingReviewCount,
+          restrictions: restrictions,
           requiredStatusCheckContexts: requiredStatusCheckContexts,
           requireBranchesToBeUpToDate: requireBranchesToBeUpToDate,
           requiredConversationResolution: requiredConversationResolution,
@@ -1632,7 +1846,8 @@ function createGithubRepoCreateAction(options) {
           hasWiki: hasWiki,
           hasIssues: hasIssues,
           token: token,
-          topics: topics
+          topics: topics,
+          requiredCommitSigning: requiredCommitSigning
         }
       },
       output: {
@@ -1717,6 +1932,8 @@ function createGithubRepoPushAction(options) {
           dismissStaleReviews: dismissStaleReviews,
           requiredStatusCheckContexts: requiredStatusCheckContexts,
           bypassPullRequestAllowances: bypassPullRequestAllowances,
+          requiredApprovingReviewCount: requiredApprovingReviewCount,
+          restrictions: restrictions,
           requireBranchesToBeUpToDate: requireBranchesToBeUpToDate,
           requiredConversationResolution: requiredConversationResolution,
           defaultBranch: defaultBranch,
@@ -1726,7 +1943,8 @@ function createGithubRepoPushAction(options) {
           gitAuthorName: gitAuthorName,
           gitAuthorEmail: gitAuthorEmail,
           sourcePath: sourcePath,
-          token: token
+          token: token,
+          requiredCommitSigning: requiredCommitSigning
         }
       },
       output: {
@@ -1749,10 +1967,13 @@ function createGithubRepoPushAction(options) {
         requireCodeOwnerReviews = false,
         dismissStaleReviews = false,
         bypassPullRequestAllowances,
+        requiredApprovingReviewCount = 1,
+        restrictions,
         requiredStatusCheckContexts = [],
         requireBranchesToBeUpToDate = true,
         requiredConversationResolution = false,
-        token: providedToken
+        token: providedToken,
+        requiredCommitSigning = false
       } = ctx.input;
       const { owner, repo } = parseRepoUrl(repoUrl, integrations);
       if (!owner) {
@@ -1781,6 +2002,8 @@ function createGithubRepoPushAction(options) {
         repo,
         requireCodeOwnerReviews,
         bypassPullRequestAllowances,
+        requiredApprovingReviewCount,
+        restrictions,
         requiredStatusCheckContexts,
         requireBranchesToBeUpToDate,
         requiredConversationResolution,
@@ -1789,7 +2012,8 @@ function createGithubRepoPushAction(options) {
         gitCommitMessage,
         gitAuthorName,
         gitAuthorEmail,
-        dismissStaleReviews
+        dismissStaleReviews,
+        requiredCommitSigning
       );
       ctx.output("remoteUrl", remoteUrl);
       ctx.output("repoContentsUrl", repoContentsUrl);
@@ -2641,6 +2865,21 @@ function createPublishBitbucketServerAction(options) {
             title: "Authentication Token",
             type: "string",
             description: "The token to use for authorization to BitBucket Server"
+          },
+          gitCommitMessage: {
+            title: "Git Commit Message",
+            type: "string",
+            description: `Sets the commit message on the repository. The default value is 'initial commit'`
+          },
+          gitAuthorName: {
+            title: "Author Name",
+            type: "string",
+            description: `Sets the author name for the commit. The default value is 'Scaffolder'`
+          },
+          gitAuthorEmail: {
+            title: "Author Email",
+            type: "string",
+            description: `Sets the author email for the commit.`
           }
         }
       },
@@ -2665,7 +2904,10 @@ function createPublishBitbucketServerAction(options) {
         description,
         defaultBranch = "master",
         repoVisibility = "private",
-        enableLFS = false
+        enableLFS = false,
+        gitCommitMessage = "initial commit",
+        gitAuthorName,
+        gitAuthorEmail
       } = ctx.input;
       const { project, repo, host } = parseRepoUrl(repoUrl, integrations);
       if (!project) {
@@ -2702,8 +2944,8 @@ function createPublishBitbucketServerAction(options) {
         apiBaseUrl
       });
       const gitAuthorInfo = {
-        name: config.getOptionalString("scaffolder.defaultAuthor.name"),
-        email: config.getOptionalString("scaffolder.defaultAuthor.email")
+        name: gitAuthorName ? gitAuthorName : config.getOptionalString("scaffolder.defaultAuthor.name"),
+        email: gitAuthorEmail ? gitAuthorEmail : config.getOptionalString("scaffolder.defaultAuthor.email")
       };
       const auth = authConfig.token ? {
         token
@@ -2717,9 +2959,7 @@ function createPublishBitbucketServerAction(options) {
         auth,
         defaultBranch,
         logger: ctx.logger,
-        commitMessage: config.getOptionalString(
-          "scaffolder.defaultCommitMessage"
-        ),
+        commitMessage: gitCommitMessage ? gitCommitMessage : config.getOptionalString("scaffolder.defaultCommitMessage"),
         gitAuthorInfo
       });
       if (enableLFS) {
@@ -3002,6 +3242,8 @@ function createPublishGithubAction(options) {
           homepage: homepage,
           access: access,
           bypassPullRequestAllowances: bypassPullRequestAllowances,
+          requiredApprovingReviewCount: requiredApprovingReviewCount,
+          restrictions: restrictions,
           requireCodeOwnerReviews: requireCodeOwnerReviews,
           dismissStaleReviews: dismissStaleReviews,
           requiredStatusCheckContexts: requiredStatusCheckContexts,
@@ -3027,7 +3269,8 @@ function createPublishGithubAction(options) {
           hasWiki: hasWiki,
           hasIssues: hasIssues,
           token: token,
-          topics: topics
+          topics: topics,
+          requiredCommitSigning: requiredCommitSigning
         }
       },
       output: {
@@ -3047,6 +3290,8 @@ function createPublishGithubAction(options) {
         requireCodeOwnerReviews = false,
         dismissStaleReviews = false,
         bypassPullRequestAllowances,
+        requiredApprovingReviewCount = 1,
+        restrictions,
         requiredStatusCheckContexts = [],
         requireBranchesToBeUpToDate = true,
         requiredConversationResolution = false,
@@ -3069,7 +3314,8 @@ function createPublishGithubAction(options) {
         hasWiki = void 0,
         hasIssues = void 0,
         topics,
-        token: providedToken
+        token: providedToken,
+        requiredCommitSigning = false
       } = ctx.input;
       const octokitOptions = await getOctokitOptions({
         integrations,
@@ -3119,6 +3365,8 @@ function createPublishGithubAction(options) {
         repo,
         requireCodeOwnerReviews,
         bypassPullRequestAllowances,
+        requiredApprovingReviewCount,
+        restrictions,
         requiredStatusCheckContexts,
         requireBranchesToBeUpToDate,
         requiredConversationResolution,
@@ -3127,7 +3375,8 @@ function createPublishGithubAction(options) {
         gitCommitMessage,
         gitAuthorName,
         gitAuthorEmail,
-        dismissStaleReviews
+        dismissStaleReviews,
+        requiredCommitSigning
       );
       ctx.output("remoteUrl", remoteUrl);
       ctx.output("repoContentsUrl", repoContentsUrl);
@@ -3155,6 +3404,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 +3603,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 +3849,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",
@@ -3826,6 +4087,7 @@ const createBuiltinActions = (options) => {
     }),
     createDebugLogAction(),
     createCatalogRegisterAction({ catalogClient, integrations }),
+    createFetchCatalogEntityAction({ catalogClient }),
     createCatalogWriteAction(),
     createFilesystemDeleteAction(),
     createFilesystemRenameAction(),
@@ -3990,6 +4252,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 +4403,7 @@ class DatabaseTaskStore {
 }
 
 class TaskManager {
+  // Runs heartbeat internally
   constructor(task, storage, logger) {
     this.task = task;
     this.storage = storage;
@@ -4223,6 +4487,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 +4508,9 @@ class StorageTaskBroker {
       await this.waitForDispatch();
     }
   }
+  /**
+   * {@inheritdoc TaskBroker.dispatch}
+   */
   async dispatch(options) {
     const taskRow = await this.storage.createTask(options);
     this.signalDispatch();
@@ -4248,9 +4518,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 +4548,9 @@ class StorageTaskBroker {
       };
     });
   }
+  /**
+   * {@inheritdoc TaskBroker.vacuumTasks}
+   */
   async vacuumTasks(options) {
     const { tasks } = await this.storage.listStaleTasks(options);
     await Promise.all(
@@ -4441,6 +4720,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 +4976,7 @@ class TaskWorker {
       workingDirectory,
       additionalTemplateFilters,
       concurrentTasksLimit = 10,
+      // from 1 to Infinity
       additionalTemplateGlobals
     } = options;
     const workflowRunner = new NunjucksWorkflowRunner({
@@ -4809,6 +5093,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 +5248,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 +5337,7 @@ async function createRouter(options) {
       return {
         id: action.id,
         description: action.description,
+        examples: action.examples,
         schema: action.schema
       };
     });
@@ -5377,71 +5664,73 @@ _actions = new WeakMap();
 const scaffolderActionsExtensionPoint = backendPluginApi.createExtensionPoint({
   id: "scaffolder.actions"
 });
-const scaffolderPlugin = backendPluginApi.createBackendPlugin({
-  id: "scaffolder",
-  register(env, options) {
-    const actionsExtensions = new ScaffolderActionsExtensionPointImpl();
-    env.registerExtensionPoint(
-      scaffolderActionsExtensionPoint,
-      actionsExtensions
-    );
-    env.registerInit({
-      deps: {
-        logger: backendPluginApi.coreServices.logger,
-        config: backendPluginApi.coreServices.config,
-        reader: backendPluginApi.coreServices.urlReader,
-        permissions: backendPluginApi.coreServices.permissions,
-        database: backendPluginApi.coreServices.database,
-        httpRouter: backendPluginApi.coreServices.httpRouter,
-        catalogClient: pluginCatalogNode.catalogServiceRef
-      },
-      async init({
-        logger,
-        config,
-        reader,
-        database,
-        httpRouter,
-        catalogClient
-      }) {
-        const {
-          additionalTemplateFilters,
-          taskBroker,
-          taskWorkers,
-          additionalTemplateGlobals
-        } = options;
-        const log = backendPluginApi.loggerToWinstonLogger(logger);
-        const actions = options.actions || [
-          ...actionsExtensions.actions,
-          ...createBuiltinActions({
-            integrations: integration.ScmIntegrations.fromConfig(config),
+const scaffolderPlugin = backendPluginApi.createBackendPlugin(
+  (options) => ({
+    id: "scaffolder",
+    register(env) {
+      const actionsExtensions = new ScaffolderActionsExtensionPointImpl();
+      env.registerExtensionPoint(
+        scaffolderActionsExtensionPoint,
+        actionsExtensions
+      );
+      env.registerInit({
+        deps: {
+          logger: backendPluginApi.coreServices.logger,
+          config: backendPluginApi.coreServices.config,
+          reader: backendPluginApi.coreServices.urlReader,
+          permissions: backendPluginApi.coreServices.permissions,
+          database: backendPluginApi.coreServices.database,
+          httpRouter: backendPluginApi.coreServices.httpRouter,
+          catalogClient: pluginCatalogNode.catalogServiceRef
+        },
+        async init({
+          logger,
+          config,
+          reader,
+          database,
+          httpRouter,
+          catalogClient
+        }) {
+          const {
+            additionalTemplateFilters,
+            taskBroker,
+            taskWorkers,
+            additionalTemplateGlobals
+          } = options;
+          const log = backendCommon.loggerToWinstonLogger(logger);
+          const actions = options.actions || [
+            ...actionsExtensions.actions,
+            ...createBuiltinActions({
+              integrations: integration.ScmIntegrations.fromConfig(config),
+              catalogClient,
+              reader,
+              config,
+              additionalTemplateFilters,
+              additionalTemplateGlobals
+            })
+          ];
+          const actionIds = actions.map((action) => action.id).join(", ");
+          log.info(
+            `Starting scaffolder with the following actions enabled ${actionIds}`
+          );
+          const router = await createRouter({
+            logger: log,
+            config,
+            database,
             catalogClient,
             reader,
-            config,
+            actions,
+            taskBroker,
+            taskWorkers,
             additionalTemplateFilters,
             additionalTemplateGlobals
-          })
-        ];
-        const actionIds = actions.map((action) => action.id).join(", ");
-        log.info(
-          `Starting scaffolder with the following actions enabled ${actionIds}`
-        );
-        const router = await createRouter({
-          logger: log,
-          config,
-          database,
-          catalogClient,
-          reader,
-          actions,
-          taskBroker,
-          taskWorkers,
-          additionalTemplateFilters,
-          additionalTemplateGlobals
-        });
-        httpRouter.use(router);
-      }
-    });
-  }
-});
+          });
+          httpRouter.use(router);
+        }
+      });
+    }
+  })
+);
 
 exports.DatabaseTaskStore = DatabaseTaskStore;
 exports.ScaffolderEntitiesProcessor = ScaffolderEntitiesProcessor;
@@ -5452,6 +5741,7 @@ exports.createBuiltinActions = createBuiltinActions;
 exports.createCatalogRegisterAction = createCatalogRegisterAction;
 exports.createCatalogWriteAction = createCatalogWriteAction;
 exports.createDebugLogAction = createDebugLogAction;
+exports.createFetchCatalogEntityAction = createFetchCatalogEntityAction;
 exports.createFetchPlainAction = createFetchPlainAction;
 exports.createFetchTemplateAction = createFetchTemplateAction;
 exports.createFilesystemDeleteAction = createFilesystemDeleteAction;