@intentius/chant 0.59.0 → 0.60.0

package/src/lifecycle/observe.test.ts

@@ -204,8 +204,8 @@ describe("observeResources", () => {
         const stack = (opts as { stack?: string }).stack;
         calls.push(stack);
         // Different resources per stack — the multi-stack, per-component case
-        // (#57 loomster). Bare-string stacks keep BARE ids (no `src` scope), so
-        // the union is `db-a`+`db-b`, not stack-qualified: per-component ids are
+        // (#57). Bare-string stacks keep BARE ids (no `src` scope), so the
+        // union is `db-a`+`db-b`, not stack-qualified: per-component ids are
         // already unique and behold reads them bare. Qualification is a scoped
         // (`src`) feature — see the per-stack src test below.
         const resources: Record<string, ResourceMetadata> =

package/src/lifecycle/observe.ts

@@ -71,10 +71,10 @@ function qualifyObservation(obs: NormalizedObservation, stackName: string): Norm
  * (`read-failed`, #1089) rather than dropped, so a failed read is visibly a
  * hole instead of a silent absence.
  *
- * `stacks` (#57) is for a multi-stack, per-component project (e.g. loomster)
- * where there is no single stack named after the environment — AWS's
- * single-stack convention (`lexicons/aws/src/plugin.ts`'s `describeResources`,
- * absent an explicit `stack`) queries a stack that simply doesn't exist there,
+ * `stacks` (#57) is for a multi-stack, per-component project, where there is no
+ * single stack named after the environment — AWS's single-stack convention
+ * (`lexicons/aws/src/plugin.ts`'s `describeResources`, absent an explicit
+ * `stack`) queries a stack that simply doesn't exist there,
  * so the single-call path always observes zero nodes. When `stacks` is
  * present and non-empty, each observing plugin's `describeResources` is
  * called once per stack and the returned observations are merged. A stack entry
@@ -197,10 +197,10 @@ export async function observeResources(
           // Qualify ids by stack ONLY for a scoped (`src`) stack (#1162): that
           // is the multi-region case where the SAME bare LogicalResourceId
           // (e.g. `vpc`) exists in every stack, so a bare union would collide.
-          // A bare-string stack (#57 loomster) has unique per-component ids and
-          // is asked the whole-project entity set, so it keeps the bare-id
-          // tri-state merge (present > not-observed > absent) that behold and
-          // other consumers read.
+          // A bare-string stack (#57) has unique per-component ids and is asked
+          // the whole-project entity set, so it keeps the bare-id tri-state
+          // merge (present > not-observed > absent) that behold and other
+          // consumers read.
           parts.push(stack.src ? qualifyObservation(norm, stack.name) : norm);
         }
         observed = mergeObservations(parts);

package/src/lifecycle/release-ledger.test.ts

@@ -256,10 +256,10 @@ describe("release-ledger", () => {
     test("a Forgejo instance resolves through the same env contract to its own host", () => {
       const env = {
         GITHUB_RUN_ID: "42",
-        GITHUB_REPOSITORY: "intentius/loomster",
+        GITHUB_REPOSITORY: "acme/widgets",
         GITHUB_SERVER_URL: "https://forge.example.dev",
       };
-      expect(resolveRunId(undefined, env).runOrigin!.url).toBe("https://forge.example.dev/intentius/loomster/actions/runs/42");
+      expect(resolveRunId(undefined, env).runOrigin!.url).toBe("https://forge.example.dev/acme/widgets/actions/runs/42");
     });
 
     test("GitLab CI env records the project path and takes CI_PIPELINE_URL verbatim", () => {

package/src/op/activities/index.ts

@@ -43,7 +43,14 @@ export type { EnvTeardownArgs, EnvTeardownResult, EnvTeardownDeps } from "./env-
 // the registry imports this module statically, so a project that installs
 // nothing but chant still resolves every step below.
 
-export { reconcilePr, commentMarker, pullRequestContextFrom, resolvePullRequestContext } from "./reconcile";
+export {
+  reconcilePr,
+  commentMarker,
+  pullRequestContextFrom,
+  resolvePullRequestContext,
+  mergeRequestContextFrom,
+  gitlabNoteTokenFrom,
+} from "./reconcile";
 export type { ReconcilePrArgs, ReconcileResult, ReconcileMode, ReconcileEntry, PullRequestContext } from "./reconcile";
 
 export { nativeApply, compensateApply, hasNativeRollback } from "./apply";

package/src/op/activities/reconcile.test.ts

@@ -6,6 +6,8 @@ import {
   entriesFromPlan,
   commentMarker,
   pullRequestContextFrom,
+  mergeRequestContextFrom,
+  gitlabNoteTokenFrom,
 } from "./reconcile";
 
 const entries = [
@@ -159,3 +161,239 @@ describe("reconcilePr comment mode refuses a run with no pull request (#2231)",
     }
   });
 });
+
+// ── The GitLab merge-request note (#2256) ───────────────────────────────────
+
+describe("mergeRequestContextFrom (#2256)", () => {
+  const gitlabEnv = {
+    CI_API_V4_URL: "https://gitlab.com/api/v4",
+    CI_PROJECT_ID: "42",
+    CI_PROJECT_PATH: "acme/infra",
+    CI_PROJECT_URL: "https://gitlab.com/acme/infra",
+    CI_MERGE_REQUEST_IID: "7",
+  };
+
+  test("reads the merge request off a merge_request_event pipeline", () => {
+    expect(mergeRequestContextFrom(gitlabEnv)).toEqual({
+      api: "https://gitlab.com/api/v4",
+      project: "42",
+      iid: 7,
+      path: "acme/infra",
+      webUrl: "https://gitlab.com/acme/infra",
+    });
+  });
+
+  test("prefers the merge request's own project over the pipeline's", () => {
+    // A merge request from a fork runs its pipeline in the fork's project,
+    // and the note belongs on the target project's merge request.
+    expect(
+      mergeRequestContextFrom({ ...gitlabEnv, CI_MERGE_REQUEST_PROJECT_ID: "9" })?.project,
+    ).toBe("9");
+  });
+
+  test("derives the API base from CI_SERVER_URL when CI_API_V4_URL is unset", () => {
+    const { CI_API_V4_URL: _drop, ...rest } = gitlabEnv;
+    expect(mergeRequestContextFrom({ ...rest, CI_SERVER_URL: "https://gl.example.com" })?.api).toBe(
+      "https://gl.example.com/api/v4",
+    );
+  });
+
+  test("a push or scheduled GitLab pipeline has no merge request", () => {
+    const { CI_MERGE_REQUEST_IID: _drop, ...rest } = gitlabEnv;
+    expect(mergeRequestContextFrom(rest)).toBeUndefined();
+    expect(mergeRequestContextFrom({ ...rest, CI_MERGE_REQUEST_IID: "" })).toBeUndefined();
+    expect(mergeRequestContextFrom({ ...rest, CI_MERGE_REQUEST_IID: "not-a-number" })).toBeUndefined();
+  });
+
+  test("a GitHub Actions run is not mistaken for a GitLab one", () => {
+    expect(mergeRequestContextFrom({ GITHUB_REPOSITORY: "INTENTIUS/chant", GITHUB_REF: "refs/pull/1/merge" })).toBeUndefined();
+  });
+});
+
+describe("gitlabNoteTokenFrom (#2256)", () => {
+  test("a project or personal access token is sent as PRIVATE-TOKEN", () => {
+    expect(gitlabNoteTokenFrom({ GITLAB_TOKEN: "glpat-x" })).toEqual({
+      header: "PRIVATE-TOKEN",
+      value: "glpat-x",
+      source: "GITLAB_TOKEN",
+    });
+  });
+
+  test("CHANT_GITLAB_TOKEN wins over GITLAB_TOKEN, which wins over the job token", () => {
+    expect(
+      gitlabNoteTokenFrom({ CHANT_GITLAB_TOKEN: "a", GITLAB_TOKEN: "b", CI_JOB_TOKEN: "c" })?.source,
+    ).toBe("CHANT_GITLAB_TOKEN");
+    expect(gitlabNoteTokenFrom({ GITLAB_TOKEN: "b", CI_JOB_TOKEN: "c" })?.source).toBe("GITLAB_TOKEN");
+  });
+
+  test("the job token is sent as JOB-TOKEN, which is a different header", () => {
+    expect(gitlabNoteTokenFrom({ CI_JOB_TOKEN: "c" })).toEqual({
+      header: "JOB-TOKEN",
+      value: "c",
+      source: "CI_JOB_TOKEN",
+    });
+  });
+
+  test("no token at all is undefined rather than an empty header", () => {
+    expect(gitlabNoteTokenFrom({})).toBeUndefined();
+    expect(gitlabNoteTokenFrom({ GITLAB_TOKEN: "", CI_JOB_TOKEN: "" })).toBeUndefined();
+  });
+});
+
+/** One stubbed GitLab REST response. */
+function gitlabResponse(body: unknown, headers: Record<string, string> = {}): Response {
+  return {
+    ok: true,
+    status: 200,
+    headers: { get: (name: string) => headers[name.toLowerCase()] ?? null },
+    json: async () => body,
+    text: async () => JSON.stringify(body),
+  } as unknown as Response;
+}
+
+describe("reconcilePr comment mode on GitLab posts one merge-request note (#2256)", () => {
+  const gitlabEnv: Record<string, string> = {
+    CI_API_V4_URL: "https://gitlab.com/api/v4",
+    CI_PROJECT_ID: "42",
+    CI_PROJECT_PATH: "acme/infra",
+    CI_PROJECT_URL: "https://gitlab.com/acme/infra",
+    CI_MERGE_REQUEST_IID: "7",
+    GITLAB_TOKEN: "glpat-x",
+  };
+
+  function stubGitlabEnv(): void {
+    for (const [k, v] of Object.entries(gitlabEnv)) vi.stubEnv(k, v);
+    // A GitLab job carries none of GitHub's variables; make that explicit so
+    // the GitHub path can never be the one under test here.
+    for (const k of ["GITHUB_REPOSITORY", "GITHUB_REF", "GITHUB_EVENT_PATH"]) vi.stubEnv(k, "");
+  }
+
+  test("POSTs a new note carrying the marker as its first line", async () => {
+    stubGitlabEnv();
+    const calls: Array<{ url: string; init?: RequestInit }> = [];
+    vi.stubGlobal("fetch", async (url: string, init?: RequestInit) => {
+      calls.push({ url, init });
+      if (!init?.method || init.method === "GET") return gitlabResponse([]);
+      return gitlabResponse({ id: 555 });
+    });
+    try {
+      const result = await reconcilePr({ env: "app", mode: "comment", body: "the plan" });
+      expect(result.commentUrl).toBe("https://gitlab.com/acme/infra/-/merge_requests/7#note_555");
+      expect(result.mergeRequest).toBe("acme/infra!7");
+      const post = calls[calls.length - 1];
+      expect(post.url).toBe("https://gitlab.com/api/v4/projects/42/merge_requests/7/notes");
+      expect(post.init?.method).toBe("POST");
+      expect((post.init?.headers as Record<string, string>)["PRIVATE-TOKEN"]).toBe("glpat-x");
+      expect(JSON.parse(String(post.init?.body)).body).toBe(
+        "<!-- chant-reconcile:app -->\n\nthe plan",
+      );
+    } finally {
+      vi.unstubAllEnvs();
+      vi.unstubAllGlobals();
+    }
+  });
+
+  test("PUTs the note it already owns instead of stacking a second one", async () => {
+    stubGitlabEnv();
+    const calls: Array<{ url: string; init?: RequestInit }> = [];
+    vi.stubGlobal("fetch", async (url: string, init?: RequestInit) => {
+      calls.push({ url, init });
+      if (!init?.method || init.method === "GET") {
+        return gitlabResponse([
+          { id: 1, system: true, body: "changed the description" },
+          { id: 2, system: false, body: "unrelated human note" },
+          { id: 3, system: false, body: "<!-- chant-reconcile:app -->\n\nan older plan" },
+        ]);
+      }
+      return gitlabResponse({ id: 3 });
+    });
+    try {
+      const result = await reconcilePr({ env: "app", mode: "comment", body: "a newer plan" });
+      const write = calls[calls.length - 1];
+      expect(write.init?.method).toBe("PUT");
+      expect(write.url).toBe("https://gitlab.com/api/v4/projects/42/merge_requests/7/notes/3");
+      expect(result.commentUrl).toBe("https://gitlab.com/acme/infra/-/merge_requests/7#note_3");
+    } finally {
+      vi.unstubAllEnvs();
+      vi.unstubAllGlobals();
+    }
+  });
+
+  test("follows GitLab's own pagination rather than reading page one alone", async () => {
+    stubGitlabEnv();
+    const seen: string[] = [];
+    vi.stubGlobal("fetch", async (url: string, init?: RequestInit) => {
+      if (!init?.method || init.method === "GET") {
+        seen.push(url);
+        if (url.endsWith("page=1")) return gitlabResponse([{ id: 1, body: "nope" }], { "x-next-page": "2" });
+        return gitlabResponse([{ id: 9, body: "<!-- chant-reconcile:app -->\n\nold" }], { "x-next-page": "" });
+      }
+      return gitlabResponse({ id: 9 });
+    });
+    try {
+      await reconcilePr({ env: "app", mode: "comment", body: "new" });
+      expect(seen).toHaveLength(2);
+      expect(seen[1]).toContain("page=2");
+    } finally {
+      vi.unstubAllEnvs();
+      vi.unstubAllGlobals();
+    }
+  });
+
+  test("a rejected write fails the step by name, carrying GitLab's own status", async () => {
+    stubGitlabEnv();
+    vi.stubGlobal("fetch", async (_url: string, init?: RequestInit) => {
+      if (!init?.method || init.method === "GET") return gitlabResponse([]);
+      return {
+        ok: false,
+        status: 403,
+        headers: { get: () => null },
+        json: async () => ({}),
+        text: async () => '{"message":"403 Forbidden"}',
+      } as unknown as Response;
+    });
+    try {
+      await expect(reconcilePr({ env: "app", mode: "comment", body: "plan" })).rejects.toThrow(
+        /merge_requests\/7\/notes.*403.*403 Forbidden/s,
+      );
+    } finally {
+      vi.unstubAllEnvs();
+      vi.unstubAllGlobals();
+    }
+  });
+
+  test("a merge-request pipeline with no token says which variable to set", async () => {
+    for (const [k, v] of Object.entries(gitlabEnv)) vi.stubEnv(k, k === "GITLAB_TOKEN" ? "" : v);
+    vi.stubEnv("CI_JOB_TOKEN", "");
+    vi.stubEnv("CHANT_GITLAB_TOKEN", "");
+    try {
+      await expect(reconcilePr({ env: "app", mode: "comment", body: "plan" })).rejects.toThrow(
+        /GITLAB_TOKEN.*CI_JOB_TOKEN/s,
+      );
+    } finally {
+      vi.unstubAllEnvs();
+    }
+  });
+});
+
+describe("the no-context refusal names both forges' variables (#2256)", () => {
+  test("a run on neither forge is told what GitLab would have set too", async () => {
+    for (const k of [
+      "GITHUB_REPOSITORY",
+      "GITHUB_REF",
+      "GITHUB_EVENT_PATH",
+      "CI_MERGE_REQUEST_IID",
+      "CI_PROJECT_ID",
+      "CI_API_V4_URL",
+    ]) {
+      vi.stubEnv(k, "");
+    }
+    try {
+      await expect(reconcilePr({ env: "app", mode: "comment", body: "plan" })).rejects.toThrow(
+        /CI_MERGE_REQUEST_IID/,
+      );
+    } finally {
+      vi.unstubAllEnvs();
+    }
+  });
+});

package/src/op/activities/reconcile.ts

@@ -12,6 +12,13 @@ const execAsync = promisify(exec);
  * re-run (chant #2231). It therefore needs a pull-request trigger, and
  * {@link resolvePullRequestContext} fails the step by name when the run has
  * none.
+ *
+ * On GitLab the same mode writes a merge-request note (chant #2256): the same
+ * marker, the same edit-in-place, a different API. Which forge a run is on is
+ * read off the run's own CI variables rather than configured — a
+ * `merge_request_event` pipeline sets `CI_MERGE_REQUEST_IID`, a GitHub
+ * `pull_request` event sets `GITHUB_REPOSITORY`, and no run sets both. See
+ * {@link mergeRequestContextFrom}.
  */
 export type ReconcileMode = "pull-request" | "issue" | "report" | "comment";
 
@@ -78,10 +85,12 @@ export interface ReconcileResult {
   prUrl?: string;
   /** Opened issue URL (issue mode). */
   issueUrl?: string;
-  /** The posted or updated PR comment's URL (comment mode). */
+  /** The posted or updated PR comment / MR note URL (comment mode). */
   commentUrl?: string;
-  /** The pull request the comment landed on, `owner/repo#number` (comment mode). */
+  /** The pull request the comment landed on, `owner/repo#number` (comment mode, GitHub). */
   pullRequest?: string;
+  /** The merge request the note landed on, `group/project!iid` (comment mode, GitLab — #2256). */
+  mergeRequest?: string;
   /** The markdown summary used as the PR/issue body. */
   summary: string;
   /** The entries that triggered the reconcile. */
@@ -142,14 +151,17 @@ export function commentMarker(env: string): string {
   return `<!-- chant-reconcile:${env.replace(/[^a-zA-Z0-9._-]+/g, "-")} -->`;
 }
 
-/** What a `comment`-mode step says when the run it is in has no pull request. */
+/** What a `comment`-mode step says when the run it is in has no pull request and no merge request. */
 export function noPullRequestContextMessage(): string {
   return (
-    'reconcilePr mode "comment" posts the finding on the pull request that triggered the run, and this run ' +
-    "has none. It needs GITHUB_REPOSITORY plus a pull request number, read from the event payload at " +
-    "GITHUB_EVENT_PATH (`.number` / `.pull_request.number`) or from GITHUB_REF (`refs/pull/<n>/merge`). " +
-    "GitHub Actions sets those on a pull_request event and on nothing else. Trigger this Op from a " +
-    'pull_request workflow, or give it findingMode "issue" or "report".'
+    'reconcilePr mode "comment" posts the finding on the pull request or merge request that triggered the ' +
+    "run, and this run has none. On GitHub Actions it needs GITHUB_REPOSITORY plus a pull request number, " +
+    "read from the event payload at GITHUB_EVENT_PATH (`.number` / `.pull_request.number`) or from " +
+    "GITHUB_REF (`refs/pull/<n>/merge`), which a pull_request event sets and nothing else does. On GitLab " +
+    "CI it needs CI_MERGE_REQUEST_IID plus the project (CI_MERGE_REQUEST_PROJECT_ID or CI_PROJECT_ID) and " +
+    "the API base (CI_API_V4_URL, or CI_SERVER_URL to derive it), which a merge_request_event pipeline " +
+    "sets and nothing else does. Trigger this Op from a pull_request or merge_request pipeline, or give " +
+    'it findingMode "issue" or "report".'
   );
 }
 
@@ -252,6 +264,226 @@ async function postOrUpdateComment(
   return stdout.trim();
 }
 
+// ── The GitLab merge-request note (#2256) ───────────────────────────────────
+
+/**
+ * The merge request a `comment`-mode run posts its note onto (#2256), as a
+ * GitLab CI job knows it. The GitLab counterpart of {@link
+ * PullRequestContext}.
+ */
+export interface MergeRequestContext {
+  /** REST v4 base, from `CI_API_V4_URL` or derived from `CI_SERVER_URL`. */
+  api: string;
+  /** The project holding the merge request — its numeric id, or a `group/project` path. */
+  project: string;
+  /** The merge request's `iid` (its per-project number, which is what the API path takes). */
+  iid: number;
+  /** `group/project`, for the human-readable `group/project!iid` on the result. */
+  path?: string;
+  /** The project's web URL, used to build the note's own URL. */
+  webUrl?: string;
+}
+
+/**
+ * Derive the triggering merge request from a GitLab job's CI variables. Pure
+ * — exported for testing, and the whole forge detection: nothing but a
+ * `merge_request_event` pipeline sets `CI_MERGE_REQUEST_IID`, so a run that
+ * has it is on GitLab and has a merge request, and a run that does not is
+ * neither.
+ *
+ * The project is the merge request's own (`CI_MERGE_REQUEST_PROJECT_ID`) in
+ * preference to the pipeline's (`CI_PROJECT_ID`): a merge request opened from
+ * a fork runs its pipeline in the fork, and the note belongs on the target
+ * project's merge request rather than on an iid that means something else in
+ * the fork.
+ *
+ * Returns undefined rather than throwing, so the caller owns the message.
+ */
+export function mergeRequestContextFrom(
+  env: Record<string, string | undefined>,
+): MergeRequestContext | undefined {
+  const rawIid = env.CI_MERGE_REQUEST_IID?.trim();
+  if (!rawIid) return undefined;
+  const iid = Number(rawIid);
+  if (!Number.isInteger(iid) || iid <= 0) return undefined;
+
+  const server = env.CI_SERVER_URL?.trim().replace(/\/+$/, "");
+  const api = env.CI_API_V4_URL?.trim().replace(/\/+$/, "") || (server ? `${server}/api/v4` : "");
+  if (!api) return undefined;
+
+  const project =
+    env.CI_MERGE_REQUEST_PROJECT_ID?.trim() ||
+    env.CI_PROJECT_ID?.trim() ||
+    env.CI_MERGE_REQUEST_PROJECT_PATH?.trim() ||
+    env.CI_PROJECT_PATH?.trim() ||
+    "";
+  if (!project) return undefined;
+
+  const path = env.CI_MERGE_REQUEST_PROJECT_PATH?.trim() || env.CI_PROJECT_PATH?.trim();
+  const webUrl = env.CI_MERGE_REQUEST_PROJECT_URL?.trim() || env.CI_PROJECT_URL?.trim();
+  return {
+    api,
+    project,
+    iid,
+    ...(path ? { path } : {}),
+    ...(webUrl ? { webUrl } : {}),
+  };
+}
+
+/** The credential a merge-request note is written with, and the header GitLab reads it from. */
+export interface GitlabNoteToken {
+  /** `PRIVATE-TOKEN` for a personal/project/group access token, `JOB-TOKEN` for `CI_JOB_TOKEN`. */
+  header: "PRIVATE-TOKEN" | "JOB-TOKEN";
+  value: string;
+  /** The variable it came from, so a refusal or a log line can name it. */
+  source: string;
+}
+
+/**
+ * Resolve the token a merge-request note is written with, most specific
+ * first. Pure — exported for testing.
+ *
+ * Two headers, not one, because GitLab reads two different credentials from
+ * two different headers: an access token goes in `PRIVATE-TOKEN`, and the
+ * pipeline's own ephemeral `CI_JOB_TOKEN` goes in `JOB-TOKEN`. Sending one in
+ * the other's header is a 401, not a fallback.
+ *
+ * The access token is preferred because it is the one that reliably works:
+ * `CI_JOB_TOKEN` reaches only the endpoints GitLab's job-token allowlist
+ * names, and the notes API is not among them on current GitLab, so a project
+ * that has not widened that allowlist needs a token with `api` scope. It is
+ * still accepted last rather than refused, so a project on an instance whose
+ * allowlist does cover notes needs no long-lived credential at all.
+ */
+export function gitlabNoteTokenFrom(
+  env: Record<string, string | undefined>,
+): GitlabNoteToken | undefined {
+  for (const source of ["CHANT_GITLAB_TOKEN", "GITLAB_TOKEN"]) {
+    const value = env[source]?.trim();
+    if (value) return { header: "PRIVATE-TOKEN", value, source };
+  }
+  const jobToken = env.CI_JOB_TOKEN?.trim();
+  if (jobToken) return { header: "JOB-TOKEN", value: jobToken, source: "CI_JOB_TOKEN" };
+  return undefined;
+}
+
+/** What a `comment`-mode step says on a merge request it has no credential for. */
+export function noGitlabNoteTokenMessage(iid: number): string {
+  return (
+    `reconcilePr mode "comment" has merge request !${iid} to post its finding on and no token to post it ` +
+    "with. Set a GITLAB_TOKEN CI/CD variable (masked, scope: api) on the project — a project access token " +
+    "is enough — or, on an instance whose job-token allowlist covers the notes API, make CI_JOB_TOKEN " +
+    "available to the job. CHANT_GITLAB_TOKEN is read first where the two must differ."
+  );
+}
+
+/** One page of merge-request notes, as much of each as this activity reads. */
+interface GitlabNote {
+  id: number;
+  body?: string;
+  /** GitLab's own generated notes ("changed the description"), never ours. */
+  system?: boolean;
+}
+
+/** GitLab's REST paths take a URL-encoded project id or `group%2Fproject` path. */
+function notesEndpoint(ctx: MergeRequestContext): string {
+  return `${ctx.api}/projects/${encodeURIComponent(ctx.project)}/merge_requests/${ctx.iid}/notes`;
+}
+
+/** One GitLab REST call, with the failure spelled out rather than swallowed into a parse error. */
+async function gitlabRequest(
+  url: string,
+  token: GitlabNoteToken,
+  init: RequestInit,
+  signal?: AbortSignal,
+): Promise<Response> {
+  const res = await fetch(url, {
+    ...init,
+    ...(signal ? { signal } : {}),
+    headers: { [token.header]: token.value, "content-type": "application/json" },
+  });
+  if (!res.ok) {
+    const detail = (await res.text().catch(() => "")).slice(0, 500);
+    throw new Error(
+      `GitLab API ${init.method ?? "GET"} ${url} answered ${res.status}${detail ? `: ${detail}` : ""} ` +
+        `(token from ${token.source}, sent as ${token.header}).`,
+    );
+  }
+  return res;
+}
+
+/**
+ * Find the note this Op already owns on `ctx`'s merge request, by the same
+ * hidden marker `postOrUpdateComment` looks a GitHub comment up by: the
+ * marker is the body's first line and the match is a prefix.
+ *
+ * Pages the way GitLab pages, following the `x-next-page` response header
+ * rather than guessing a page count — an active merge request runs past one
+ * page of notes routinely, and a lookup that read page one alone would post
+ * a second comment instead of editing the first.
+ *
+ * GitLab's own system notes are skipped: they are the activity feed
+ * ("changed the description"), they are never ours, and they are the bulk of
+ * what fills those pages.
+ */
+async function findOwnedNote(
+  ctx: MergeRequestContext,
+  token: GitlabNoteToken,
+  marker: string,
+  signal?: AbortSignal,
+): Promise<number | undefined> {
+  const endpoint = notesEndpoint(ctx);
+  // A merge request with more notes than this has something other than a
+  // stale plan comment wrong with it; the bound is what stops a broken
+  // `x-next-page` header from looping forever.
+  const MAX_PAGES = 50;
+  for (let page = 1; page <= MAX_PAGES; page++) {
+    const res = await gitlabRequest(`${endpoint}?per_page=100&page=${page}`, token, { method: "GET" }, signal);
+    const notes = (await res.json()) as GitlabNote[];
+    const owned = notes.find((note) => !note.system && (note.body ?? "").startsWith(marker));
+    if (owned) return owned.id;
+    const next = res.headers.get("x-next-page")?.trim();
+    if (!next) return undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Post `body` as one note on `ctx`'s merge request, or edit the note this Op
+ * already owns there — {@link postOrUpdateComment}'s GitLab half, and the
+ * same recipe: find by marker, PUT when there is one, POST when there is not,
+ * so a merge request pushed to five times carries one note holding the
+ * current finding rather than five stale ones.
+ *
+ * Over `fetch` rather than a CLI. `gh` is on GitHub's hosted runners and is
+ * already this activity's dependency for the issue and pull-request modes;
+ * `glab` is on no GitLab runner by default, and a job whose finding step
+ * depended on it would fail on the ordinary `node:22-slim` image the
+ * generator emits.
+ */
+async function postOrUpdateNote(
+  ctx: MergeRequestContext,
+  token: GitlabNoteToken,
+  marker: string,
+  body: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  const endpoint = notesEndpoint(ctx);
+  const existing = await findOwnedNote(ctx, token, marker, signal);
+  const payload = JSON.stringify({ body: `${marker}\n\n${body}` });
+  const res = existing
+    ? await gitlabRequest(`${endpoint}/${existing}`, token, { method: "PUT", body: payload }, signal)
+    : await gitlabRequest(endpoint, token, { method: "POST", body: payload }, signal);
+  const note = (await res.json()) as GitlabNote;
+  // GitLab's note payload carries no web URL, unlike GitHub's comment. The
+  // anchor is how the UI itself addresses a note, so it is built rather than
+  // read; with no project web URL to build it from, the API path is at least
+  // a resolvable address for the thing that was written.
+  return ctx.webUrl
+    ? `${ctx.webUrl}/-/merge_requests/${ctx.iid}#note_${note.id}`
+    : `${endpoint}/${note.id}`;
+}
+
 /**
  * Map a `chant lifecycle plan --json` ChangeSet to reconcile entries, dropping
  * `noop` entries (nothing to reconcile). Pure — exported for testing.
@@ -286,10 +518,13 @@ async function derivePlanEntries(
  * - `issue` — open a GitHub issue describing the drift (no code change).
  * - `comment` — post the body as one comment on the pull request that
  *   triggered the run, editing that same comment on every re-run rather than
- *   stacking a new one (#2231). Needs a pull-request-triggered run; fails by
- *   name when there is none. No code change, and the `pull-requests: write`
- *   the generated workflow already grants on that trigger is the whole scope
- *   it spends.
+ *   stacking a new one (#2231), or, on a GitLab `merge_request_event`
+ *   pipeline, as one note on that merge request by the same recipe (#2256).
+ *   Needs a pull-request- or merge-request-triggered run; fails by name when
+ *   there is none. No code change, and the `pull-requests: write` the
+ *   generated workflow already grants on that trigger is the whole scope it
+ *   spends on GitHub; on GitLab the scope is whatever the token it is given
+ *   carries.
  * - `pull-request` — create a branch, regenerate source via
  *   `chant import --from <env>`, commit, push, and open a PR whose diff is the
  *   regenerated TypeScript. Never commits to the main branch.
@@ -325,8 +560,27 @@ export async function reconcilePr(args: ReconcilePrArgs, signal?: AbortSignal):
     // The trigger context is read here rather than passed in: a step's args
     // are serialized at build time, and the pull request is not known until
     // the run. Missing context is fatal — see `noPullRequestContextMessage`.
-    const ctx = await resolvePullRequestContext();
     const marker = args.marker ?? commentMarker(args.env);
+
+    // GitLab first, because its check is the narrow one: only a
+    // `merge_request_event` pipeline sets `CI_MERGE_REQUEST_IID` (#2256), so
+    // a run that has it is unambiguously the GitLab case, and a GitHub run
+    // never reaches this branch.
+    const mr = mergeRequestContextFrom(process.env);
+    if (mr) {
+      const token = gitlabNoteTokenFrom(process.env);
+      if (!token) throw new Error(noGitlabNoteTokenMessage(mr.iid));
+      const commentUrl = await postOrUpdateNote(mr, token, marker, summary, signal);
+      return {
+        mode,
+        summary,
+        entries,
+        commentUrl,
+        mergeRequest: `${mr.path ?? mr.project}!${mr.iid}`,
+      };
+    }
+
+    const ctx = await resolvePullRequestContext();
     const commentUrl = await postOrUpdateComment(ctx, marker, summary, signal);
     return { mode, summary, entries, commentUrl, pullRequest: `${ctx.repo}#${ctx.number}` };
   }