@catladder/cli 5.6.0 → 5.7.1

package/package.json

@@ -53,7 +53,7 @@
     }
   ],
   "license": "MIT",
-  "version": "5.6.0",
+  "version": "5.7.1",
   "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/__tests__/github.test.ts

@@ -0,0 +1,118 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { githubReviewDeployGuardJob } from "../github";
+
+const HEAD = "4a60abe0000000000000000000000000000000aa";
+
+type Call = { url: string; method: string; body?: any };
+
+/** a github api double: one PR, a `catladder ✅` check in a given state */
+const mockGithub = (
+  check: { status: string; conclusion: string | null } | null,
+) => {
+  const calls: Call[] = [];
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (url: string, init: any = {}) => {
+      const path = url.replace("https://api.github.com/repos/o/r/", "");
+      calls.push({
+        url: path,
+        method: init.method ?? "GET",
+        body: init.body ? JSON.parse(init.body) : undefined,
+      });
+      const json = (data: unknown) => ({
+        ok: true,
+        status: 200,
+        json: async () => data,
+        text: async () => JSON.stringify(data),
+      });
+      if (path.startsWith("pulls/")) {
+        return json({
+          number: 159,
+          state: "open",
+          draft: false,
+          labels: [{ name: "catladder:review-app" }],
+          head: { sha: HEAD, ref: "feat/x" },
+        });
+      }
+      if (path.startsWith("commits/")) {
+        return json({ check_runs: check ? [{ id: 1, ...check }] : [] });
+      }
+      return json({});
+    }),
+  );
+  return calls;
+};
+
+describe("review deploy guard: label added while the CI runs", () => {
+  let output: string;
+  beforeEach(() => {
+    output = "";
+    vi.spyOn(console, "log").mockImplementation(() => {});
+    process.env.GITHUB_REPOSITORY = "o/r";
+    process.env.GITHUB_TOKEN = "t";
+    process.env.GITHUB_RUN_ID = "1";
+    process.env.CL_PR_NUMBER = "159";
+    process.env.CL_HEAD_SHA = HEAD;
+    process.env.CL_DEPLOY_SOURCE = "label";
+    process.env.CL_REVIEW_APPS = JSON.stringify({
+      deploy: "optIn",
+      label: "catladder:review-app",
+      skipLabel: "catladder:no-review-app",
+      drafts: "likeReady",
+    });
+    // capture the step output
+    const file = `${process.env.TMPDIR ?? "/tmp"}/gh-output-${process.pid}-${Math.random()}`;
+    process.env.GITHUB_OUTPUT = file;
+    output = file;
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+  const deployOutput = async () =>
+    (await import("fs")).readFileSync(output, "utf8");
+
+  it("defers and reports a pending status while the CI is not finished", async () => {
+    const calls = mockGithub({ status: "in_progress", conclusion: null });
+    await githubReviewDeployGuardJob();
+    expect(await deployOutput()).toContain("deploy=false");
+    const status = calls.find((c) => c.url === `statuses/${HEAD}`);
+    expect(status?.method).toBe("POST");
+    expect(status?.body).toMatchObject({
+      state: "pending",
+      context: "catladder review app",
+    });
+    expect(status?.body.description).toContain("waiting for the CI");
+  });
+
+  it("defers and reports pending while the CI has not even reported", async () => {
+    const calls = mockGithub(null);
+    await githubReviewDeployGuardJob();
+    expect(await deployOutput()).toContain("deploy=false");
+    expect(calls.some((c) => c.url === `statuses/${HEAD}`)).toBe(true);
+  });
+
+  it("deploys without a pending status when the CI already finished green", async () => {
+    const calls = mockGithub({ status: "completed", conclusion: "success" });
+    await githubReviewDeployGuardJob();
+    expect(await deployOutput()).toContain("deploy=true");
+    expect(calls.some((c) => c.url.startsWith("statuses/"))).toBe(false);
+  });
+
+  it("trusts a ci dispatch: deploys although the checks api still reports the CI in progress", async () => {
+    process.env.CL_DEPLOY_SOURCE = "ci";
+    const calls = mockGithub({ status: "in_progress", conclusion: null });
+    await githubReviewDeployGuardJob();
+    expect(await deployOutput()).toContain("deploy=true");
+    expect(calls.some((c) => c.url.startsWith("commits/"))).toBe(false);
+    expect(calls.some((c) => c.url.startsWith("statuses/"))).toBe(false);
+  });
+
+  it("a ci dispatch for a head the PR moved away from does not deploy", async () => {
+    process.env.CL_DEPLOY_SOURCE = "ci";
+    process.env.CL_HEAD_SHA = "0000000000000000000000000000000000000000";
+    mockGithub({ status: "completed", conclusion: "success" });
+    await githubReviewDeployGuardJob();
+    expect(await deployOutput()).toContain("deploy=false");
+  });
+});