@catladder/cli 5.5.0 → 5.7.0

package/package.json

@@ -53,7 +53,7 @@
     }
   ],
   "license": "MIT",
-  "version": "5.5.0",
+  "version": "5.7.0",
   "scripts": {
     "lint": "eslint \"src/**/*.ts\"",
     "lint:fix": "eslint \"src/**/*.ts\" --fix",

package/src/catci.ts

@@ -30,6 +30,10 @@ import {
   githubQueuedGuardJob,
 } from "./release/githubQueuedRelease";
 import { npmPublishJob, parseNpmPublishArgs } from "./publish/npmPublishJob";
+import {
+  githubReviewDeployGuardJob,
+  githubReviewDeployTriggerJob,
+} from "./reviewApps/github";
 import { getGitlabHostUrl } from "./utils/gitlabHost";
 
 const USAGE = `catci — catladder CI companion
@@ -78,6 +82,17 @@ usage:
       queue marker when it matches the completed main run and decides
       whether the release step runs (release=true step output)
 
+  catci review-app github-trigger
+      github only, last job of the review workflow: once the PR's CI is
+      green, dispatches the review deploy workflow when the reviewApps
+      policy (labels, draft) says the PR deploys
+
+  catci review-app github-guard
+      github only, first job of the review deploy workflow: decides
+      whether the run deploys (deploy=true step output) — explicit
+      dispatches always do, label events and ci dispatches follow the
+      policy; all need the PR open and its CI green
+
   catci publish npm --dir <dir> --env-type <envType> [--access <access>] [--registry <url>] [--dist-tag <tag>]
       npmPackage deploy job: derives version + dist-tag from the
       pipeline trigger (tagged release -> tag version @latest; branch/MR
@@ -204,6 +219,20 @@ const main = async () => {
   ) {
     return githubQueuedGuardJob(args[0], args[1]);
   }
+  if (
+    group === "review-app" &&
+    command === "github-trigger" &&
+    args.length === 0
+  ) {
+    return githubReviewDeployTriggerJob();
+  }
+  if (
+    group === "review-app" &&
+    command === "github-guard" &&
+    args.length === 0
+  ) {
+    return githubReviewDeployGuardJob();
+  }
   if (group === "publish" && command === "npm") {
     const options = parseNpmPublishArgs(args);
     if (options) {

package/src/commands/index.ts

@@ -30,6 +30,10 @@ export { commandCiJobOpen, commandCiJobLog } from "./project/commandGitlabCi";
 export { commandProjectRestoreDb } from "./project/commandProjectRestoreDb";
 export { commandSecurityEvaluate } from "./project/commandSecurityEvaluate";
 export { commandMrPin, commandMrUnpin } from "./project/commandMrPin";
+export {
+  commandMrReviewAppOn,
+  commandMrReviewAppOff,
+} from "./project/commandMrReviewApp";
 
 // Project k8s commands
 export { commandNamespace } from "./project/k8s/commandNamespace";

package/src/commands/project/commandMrPin.ts

@@ -10,7 +10,7 @@ import { doGitlabRequest, getProjectInfo } from "../../utils/gitlab";
 
 const PIN_LABEL_COLOR = "#428fdc";
 
-type GitlabMr = {
+export type GitlabMr = {
   iid: number;
   title: string;
   web_url: string;
@@ -40,7 +40,7 @@ const getPinLabel = async (): Promise<string> => {
   return pinLabel;
 };
 
-const findMr = async (
+export const findMr = async (
   io: IO,
   projectId: string,
   mrIid: number | undefined,
@@ -61,30 +61,26 @@ const findMr = async (
   return mrs[0];
 };
 
-const ensurePinLabelExists = async (
+export const ensureLabelExists = async (
   io: IO,
   projectId: string,
-  pinLabel: string,
+  name: string,
+  description: string,
 ) => {
   const existing = await doGitlabRequest<Array<{ name: string }>>(
     io,
-    `projects/${projectId}/labels?search=${encodeURIComponent(pinLabel)}`,
+    `projects/${projectId}/labels?search=${encodeURIComponent(name)}`,
   );
-  if (existing?.some((label) => label.name === pinLabel)) {
+  if (existing?.some((label) => label.name === name)) {
     return;
   }
   await doGitlabRequest(
     io,
     `projects/${projectId}/labels`,
-    {
-      name: pinLabel,
-      color: PIN_LABEL_COLOR,
-      description:
-        "review apps of this MR are pinned — deploys use auto_stop_in: never (managed by catladder)",
-    },
+    { name, color: PIN_LABEL_COLOR, description },
     "POST",
   );
-  io.log(`created the '${pinLabel}' label in the project`);
+  io.log(`created the '${name}' label in the project`);
 };
 
 export const commandMrPin = defineCommand({
@@ -112,7 +108,12 @@ export const commandMrPin = defineCommand({
     const { id: projectId } = await getProjectInfo(ctx);
     const mr = await findMr(ctx, projectId, await ctx.get("mr"));
 
-    await ensurePinLabelExists(ctx, projectId, pinLabel);
+    await ensureLabelExists(
+      ctx,
+      projectId,
+      pinLabel,
+      "review apps of this MR are pinned — deploys use auto_stop_in: never (managed by catladder)",
+    );
 
     if (mr.labels?.includes(pinLabel)) {
       ctx.log(`already pinned: mr!${mr.iid} carries the '${pinLabel}' label`);

package/src/commands/project/commandMrReviewApp.ts

@@ -0,0 +1,143 @@
+import {
+  getEnabledPipelineTypes,
+  getReviewAppsConfig,
+  getReviewAppsSwitchLabel,
+} from "@catladder/pipeline";
+import { getProjectConfig } from "../../config/getProjectConfig";
+import { defineCommand } from "../../core/defineCommand";
+import { doGitlabRequest, getProjectInfo } from "../../utils/gitlab";
+import { ensureLabelExists, findMr } from "./commandMrPin";
+
+/**
+ * the label switch of the project's review apps — errors when the
+ * project has none (github, or a policy without labels)
+ */
+const getSwitch = async () => {
+  const config = await getProjectConfig();
+  if (!config) {
+    throw new Error("no catladder config found");
+  }
+  const reviewApps = getReviewAppsConfig(config);
+  const switchLabel = getReviewAppsSwitchLabel(reviewApps);
+  if (!switchLabel) {
+    throw new Error(
+      reviewApps.deploy === "manual"
+        ? "review apps deploy on request in this project (reviewApps.deploy: manual) — play the '🚀 deploy review' job of the MR pipeline"
+        : "review apps of this project are not switched by label (set reviewApps.deploy to optIn or optOut)",
+    );
+  }
+  if (!getEnabledPipelineTypes(config).includes("gitlab")) {
+    throw new Error(
+      `this command switches gitlab merge requests — on github, set the label on the pull request instead (gh pr edit --${switchLabel.deployOn === "labeled" ? "add" : "remove"}-label ${switchLabel.label}); the label change deploys by itself`,
+    );
+  }
+  return switchLabel;
+};
+
+const mrInput = {
+  mr: {
+    type: "number",
+    message:
+      "merge request IID (defaults to the open MR of the current branch)",
+    positional: true,
+    required: false,
+  },
+} as const;
+
+export const commandMrReviewAppOn = defineCommand({
+  name: "mr review-app-on",
+  description:
+    "deploy the review apps of a merge request: switches the reviewApps label on (opt-in: adds it, opt-out: removes the skip label) and triggers a pipeline, since gitlab doesn't start one for label changes",
+  group: "mr",
+  inputs: {
+    ...mrInput,
+    pipeline: {
+      type: "boolean",
+      message: "trigger a merge-request pipeline so the review apps deploy now",
+      required: false,
+    },
+  },
+  execute: async (ctx) => {
+    const switchLabel = await getSwitch();
+    const { id: projectId } = await getProjectInfo(ctx);
+    const mr = await findMr(ctx, projectId, await ctx.get("mr"));
+
+    if (switchLabel.deployOn === "labeled") {
+      await ensureLabelExists(
+        ctx,
+        projectId,
+        switchLabel.label,
+        "review apps of this MR deploy (managed by catladder)",
+      );
+    }
+    const hasLabel = mr.labels?.includes(switchLabel.label);
+    if (hasLabel === (switchLabel.deployOn === "labeled")) {
+      ctx.log(`review apps of mr!${mr.iid} are already switched on`);
+    } else {
+      await doGitlabRequest(
+        ctx,
+        `projects/${projectId}/merge_requests/${mr.iid}`,
+        switchLabel.deployOn === "labeled"
+          ? { add_labels: switchLabel.label }
+          : { remove_labels: switchLabel.label },
+        "PUT",
+      );
+      ctx.log(
+        `review apps of mr!${mr.iid} "${mr.title}" switched on — label '${switchLabel.label}' ${switchLabel.deployOn === "labeled" ? "added" : "removed"}`,
+      );
+    }
+
+    if ((await ctx.get("pipeline")) ?? true) {
+      const pipeline = await doGitlabRequest<{ web_url: string }>(
+        ctx,
+        `projects/${projectId}/merge_requests/${mr.iid}/pipelines`,
+        {},
+        "POST",
+      );
+      ctx.log(`🚀 triggered a pipeline that deploys them: ${pipeline.web_url}`);
+    } else {
+      ctx.log("the review apps deploy with the next pipeline of the MR");
+    }
+  },
+});
+
+export const commandMrReviewAppOff = defineCommand({
+  name: "mr review-app-off",
+  description:
+    "stop deploying the review apps of a merge request: switches the reviewApps label off (opt-in: removes it, opt-out: adds the skip label). Running review apps stay until the MR closes or they auto-stop",
+  group: "mr",
+  inputs: mrInput,
+  execute: async (ctx) => {
+    const switchLabel = await getSwitch();
+    const { id: projectId } = await getProjectInfo(ctx);
+    const mr = await findMr(ctx, projectId, await ctx.get("mr"));
+
+    if (switchLabel.stopOn === "labeled") {
+      await ensureLabelExists(
+        ctx,
+        projectId,
+        switchLabel.label,
+        "review apps of this MR don't deploy (managed by catladder)",
+      );
+    }
+    const hasLabel = mr.labels?.includes(switchLabel.label);
+    if (hasLabel === (switchLabel.stopOn === "labeled")) {
+      ctx.log(`review apps of mr!${mr.iid} are already switched off`);
+      return;
+    }
+    await doGitlabRequest(
+      ctx,
+      `projects/${projectId}/merge_requests/${mr.iid}`,
+      switchLabel.stopOn === "labeled"
+        ? { add_labels: switchLabel.label }
+        : { remove_labels: switchLabel.label },
+      "PUT",
+    );
+    ctx.log(
+      `review apps of mr!${mr.iid} switched off — label '${switchLabel.label}' ${switchLabel.stopOn === "labeled" ? "added" : "removed"}`,
+    );
+    ctx.log(
+      "already running review apps stay until the MR is closed or they auto-stop — stop them earlier with the stop job of the MR pipeline",
+    );
+  },
+});

package/src/reviewApps/github.ts

@@ -0,0 +1,253 @@
+/**
+ * the review deploy switch on github (see the pipeline's
+ * `reviewApps.ts` and `backends/github/reviewDeployWorkflow.ts`).
+ *
+ * github runs can't pause for a click, so the switch is a workflow of
+ * its own, `▶️ catladder deploy review`, holding the review delivery
+ * chains (docker → deploy → verify) behind a guard:
+ *
+ * - `github-trigger` is the last job of the review workflow: once the
+ *   PR's CI is green it reads the PR fresh (labels, draft) and
+ *   dispatches the deploy workflow when the policy says it deploys
+ * - `github-guard` is the first job of the deploy workflow and decides
+ *   whether the run deploys (`deploy` step output):
+ *   - source `manual` (a dispatch by a human or agent): always,
+ *     provided the PR is open and its CI is green
+ *   - source `ci` (dispatched by the trigger) and `label` (the switch
+ *     label changed / a draft was marked ready): when the policy says
+ *     so — and the CI is green. A label switched on while CI still runs
+ *     is no deploy here: the trigger picks it up once CI is green.
+ */
+import {
+  type ResolvedReviewAppsConfig,
+  shouldAutoDeployReviewApps,
+} from "../../../../packages/pipeline/src/reviewAppsPolicy";
+import { appendFileSync } from "fs";
+import { appendStepSummary, workflowLink } from "../release/stepSummary";
+
+/**
+ * the generated review deploy workflow. Keep in sync with
+ * REVIEW_DEPLOY_WORKFLOW_FILE in
+ * packages/pipeline/src/backends/github/reviewDeployWorkflow.ts.
+ */
+const GITHUB_REVIEW_DEPLOY_WORKFLOW = "catladder-deploy-review.yml";
+
+/**
+ * the review workflow's aggregate job — its check run says whether the
+ * PR's CI is green. Keep in sync with AGGREGATE_CHECK_JOB_NAME in
+ * packages/pipeline/src/backends/github/aggregateCheckJob.ts.
+ */
+const AGGREGATE_CHECK_NAME = "catladder ✅";
+
+type PullRequest = {
+  number: number;
+  state: string;
+  draft: boolean;
+  labels: Array<{ name: string }>;
+  head: { sha: string; ref: string };
+};
+
+const requireEnv = (name: string): string => {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`${name} is not set`);
+  }
+  return value;
+};
+
+const fail = (message: string): never => {
+  console.error(message);
+  process.exit(1);
+};
+
+const setStepOutput = (name: string, value: string) => {
+  const file = process.env.GITHUB_OUTPUT;
+  if (file) {
+    appendFileSync(file, `${name}=${value}\n`);
+  }
+};
+
+const getReviewAppsConfig = (): ResolvedReviewAppsConfig =>
+  JSON.parse(requireEnv("CL_REVIEW_APPS"));
+
+const githubApi = async (path: string, init: RequestInit = {}) => {
+  const apiUrl = process.env.GITHUB_API_URL ?? "https://api.github.com";
+  const repository = requireEnv("GITHUB_REPOSITORY");
+  return fetch(`${apiUrl}/repos/${repository}/${path}`, {
+    ...init,
+    headers: {
+      authorization: `Bearer ${requireEnv("GITHUB_TOKEN")}`,
+      accept: "application/vnd.github+json",
+      ...init.headers,
+    },
+  });
+};
+
+const getPullRequest = async (prNumber: string): Promise<PullRequest> => {
+  const response = await githubApi(`pulls/${prNumber}`);
+  if (!response.ok) {
+    throw new Error(
+      `reading pull request #${prNumber} failed: ${response.status} ${await response.text()}`,
+    );
+  }
+  return (await response.json()) as PullRequest;
+};
+
+/**
+ * the newest `catladder ✅` check run of a commit — null while the
+ * review workflow hasn't reported yet
+ */
+const getAggregateCheck = async (
+  sha: string,
+): Promise<{ status: string; conclusion: string | null } | null> => {
+  const response = await githubApi(
+    `commits/${sha}/check-runs?check_name=${encodeURIComponent(AGGREGATE_CHECK_NAME)}&filter=latest`,
+  );
+  if (!response.ok) {
+    throw new Error(
+      `reading the checks of ${sha} failed: ${response.status} ${await response.text()}`,
+    );
+  }
+  const data = (await response.json()) as {
+    check_runs?: Array<{
+      id: number;
+      status: string;
+      conclusion: string | null;
+    }>;
+  };
+  const [newest] = [...(data.check_runs ?? [])].sort((a, b) => b.id - a.id);
+  return newest ?? null;
+};
+
+const short = (sha: string) => sha.slice(0, 7);
+
+const mrState = (pr: PullRequest) => ({
+  labels: pr.labels.map((label) => label.name),
+  draft: pr.draft,
+});
+
+/**
+ * `catci review-app github-guard` — first job of the review deploy
+ * workflow, sets the `deploy` step output
+ */
+export const githubReviewDeployGuardJob = async () => {
+  const config = getReviewAppsConfig();
+  const prNumber = requireEnv("CL_PR_NUMBER");
+  const source = process.env.CL_DEPLOY_SOURCE || "manual";
+  const headSha = requireEnv("CL_HEAD_SHA");
+  const explicit = source === "manual";
+
+  const skip = (message: string) => {
+    console.log(`not deploying: ${message}`);
+    appendStepSummary(`⏭️ **Not deploying** the review apps: ${message}`);
+    setStepOutput("deploy", "false");
+  };
+  // an explicit request that can't be served is an error, an automatic
+  // one simply doesn't deploy
+  const refuse = (message: string) => {
+    if (explicit) {
+      appendStepSummary(`❌ **Can't deploy** the review apps: ${message}`);
+      setStepOutput("deploy", "false");
+      fail(`can't deploy the review apps: ${message}`);
+    }
+    skip(message);
+  };
+
+  const pr = await getPullRequest(prNumber);
+  if (pr.state !== "open") {
+    return refuse(`pull request #${pr.number} is ${pr.state}`);
+  }
+  let reason = "requested explicitly";
+  if (!explicit) {
+    const decision = shouldAutoDeployReviewApps(config, mrState(pr));
+    if (!decision.deploy) {
+      return skip(decision.reason);
+    }
+    reason = decision.reason;
+  }
+  if (pr.head.sha !== headSha) {
+    return refuse(
+      explicit
+        ? `this run is for ${short(headSha)}, but #${pr.number}'s head is ${short(pr.head.sha)} — dispatch the workflow from the pull request's branch ('${pr.head.ref}')`
+        : `#${pr.number} moved on to ${short(pr.head.sha)} — its own review run decides`,
+    );
+  }
+  const check = await getAggregateCheck(headSha);
+  if (!check || check.status !== "completed") {
+    return refuse(
+      `the CI of ${short(headSha)} (${AGGREGATE_CHECK_NAME}) is not finished yet` +
+        (explicit
+          ? " — dispatch again once it is green"
+          : " — the review workflow starts the deploy once it is green"),
+    );
+  }
+  if (check.conclusion !== "success") {
+    return refuse(
+      `the CI of ${short(headSha)} (${AGGREGATE_CHECK_NAME}) concluded '${check.conclusion}'`,
+    );
+  }
+  console.log(
+    `deploying the review apps of #${pr.number} (${short(headSha)}): ${reason}`,
+  );
+  appendStepSummary(
+    `🚀 **Deploying** the review apps of #${pr.number} (\`${short(headSha)}\`): ${reason}.`,
+  );
+  setStepOutput("deploy", "true");
+};
+
+/**
+ * `catci review-app github-trigger` — last job of the review workflow:
+ * dispatches the review deploy workflow when the PR deploys
+ */
+export const githubReviewDeployTriggerJob = async () => {
+  const config = getReviewAppsConfig();
+  const prNumber = requireEnv("CL_PR_NUMBER");
+  const headRef = requireEnv("CL_HEAD_REF");
+  const headSha = requireEnv("CL_HEAD_SHA");
+
+  const pr = await getPullRequest(prNumber);
+  if (pr.head.sha !== headSha) {
+    console.log(
+      `#${pr.number} moved on to ${short(pr.head.sha)} — its own review run decides`,
+    );
+    return;
+  }
+  const decision = shouldAutoDeployReviewApps(config, mrState(pr));
+  if (!decision.deploy) {
+    console.log(`not deploying the review apps: ${decision.reason}`);
+    appendStepSummary(
+      `⏭️ Review apps not deployed: ${decision.reason}. ` +
+        `Deploy anyway: \`gh workflow run ${GITHUB_REVIEW_DEPLOY_WORKFLOW} --ref ${headRef} -f pr=${pr.number}\``,
+    );
+    return;
+  }
+  const response = await githubApi(
+    `actions/workflows/${GITHUB_REVIEW_DEPLOY_WORKFLOW}/dispatches`,
+    {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        ref: headRef,
+        inputs: { pr: String(pr.number), source: "ci" },
+      }),
+    },
+  );
+  if (response.status === 404) {
+    // github only dispatches workflows that exist on the default branch
+    const message = `the ${GITHUB_REVIEW_DEPLOY_WORKFLOW} workflow is not on the default branch yet — review apps deploy automatically once this change is merged`;
+    console.log(`::warning::${message}`);
+    appendStepSummary(`⚠️ ${message}`);
+    return;
+  }
+  if (!response.ok) {
+    fail(
+      `dispatching ${GITHUB_REVIEW_DEPLOY_WORKFLOW} failed: ${response.status} ${await response.text()}`,
+    );
+  }
+  console.log(
+    `review deploy dispatched for #${pr.number} (${short(headSha)}): ${decision.reason}`,
+  );
+  appendStepSummary(
+    `▶️ **Review deploy started** for #${pr.number} (\`${short(headSha)}\`): ${decision.reason} — see ${workflowLink(GITHUB_REVIEW_DEPLOY_WORKFLOW, "catladder deploy review")}.`,
+  );
+};