@intentius/chant 0.61.0 → 0.62.0

package/src/op/activities/reconcile.ts

@@ -19,6 +19,34 @@ const execAsync = promisify(exec);
  * `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}.
+ *
+ * On Forgejo the same mode posts the same GitHub-shaped comment (chant
+ * #2291): no forge split at all, because a Forgejo Actions job already sets
+ * `GITHUB_REPOSITORY`, `GITHUB_API_URL` and `github.token` the same way a
+ * GitHub Actions job does, and Forgejo's own `/api/v1` takes the identical
+ * GET/POST/PATCH triple. The one thing that needed fixing was the URL: `gh
+ * api` resolves a *relative* path against `/api/v3` for any host other than
+ * `github.com`, and Forgejo does not serve `/api/v3` — verified on a real
+ * Forgejo 12.0.4+gitea-1.22.0 instance during INTENTIUS/choudoufu#1027. See
+ * {@link postOrUpdateComment} and {@link githubApiBaseFrom}.
+ *
+ * `issue` needs no merge/pull request — its whole point is a cron trigger
+ * that has none — so its forge split reads off a wider signal: any GitLab CI
+ * job sets `CI_PROJECT_ID`, not only a merge-request one (see {@link
+ * gitlabProjectContextFrom}), and any GitHub Actions or Forgejo Actions job
+ * sets `GITHUB_REPOSITORY`. Both are sticky now (chant #2292, #2297): each
+ * finds and edits the OPEN issue it already owns by a hidden marker, the same
+ * recipe `comment` mode's note uses, and opens a new one only when it finds
+ * none. See {@link postOrUpdateGithubIssue} for the GitHub/GHES/Forgejo half
+ * — including why it does not use GitHub's Search API, and the decision that
+ * this mode never closes the issue itself. Only a run outside any known CI
+ * job — no `CI_PROJECT_ID`, no `GITHUB_REPOSITORY` — falls back to `gh issue
+ * create`'s own ambient repo detection, still marker-prefixed so a later CI
+ * run of the same Op finds and edits it instead of opening a second one. `gh
+ * api` was not exercised against a real Forgejo instance for this mode (only
+ * the `comment` mode's endpoints were, chant #2291) — the request shape
+ * mirrors that mode's exactly, but the search behavior itself is the one
+ * part a mock cannot vouch for.
  */
 export type ReconcileMode = "pull-request" | "issue" | "report" | "comment";
 
@@ -52,11 +80,12 @@ export interface ReconcilePrArgs {
   /** PR / issue title. Default derived from env. */
   title?: string;
   /**
-   * Hidden marker identifying this Op's comment on the pull request (comment
-   * mode). The activity writes it as the comment's first line and finds the
-   * comment again by it on the next run, so a re-run edits one comment instead
-   * of stacking a new one. Default: {@link commentMarker} keyed on `env`, so
-   * two Ops over two roots get two comments and each updates in place.
+   * Hidden marker identifying this Op's own comment or issue. The activity
+   * writes it as the first line and finds it again by it on the next run, so
+   * a re-run edits one comment/issue instead of stacking a new one. Default:
+   * {@link commentMarker} for `comment` mode, {@link issueMarker} for `issue`
+   * mode, both keyed on `env`, so two Ops over two roots get two comments (or
+   * two issues) and each updates in place.
    */
   marker?: string;
   /**
@@ -83,7 +112,7 @@ export interface ReconcileResult {
   branch?: string;
   /** Opened PR URL (pull-request mode). */
   prUrl?: string;
-  /** Opened issue URL (issue mode). */
+  /** Opened or edited issue URL (issue mode; sticky on every forge — #2292, #2297). */
   issueUrl?: string;
   /** The posted or updated PR comment / MR note URL (comment mode). */
   commentUrl?: string;
@@ -151,6 +180,20 @@ export function commentMarker(env: string): string {
   return `<!-- chant-reconcile:${env.replace(/[^a-zA-Z0-9._-]+/g, "-")} -->`;
 }
 
+/**
+ * The hidden marker that makes an `issue`-mode GitLab finding findable across
+ * re-runs (#2292): written as the issue description's first line, matched by
+ * a server-side `search` plus a `startswith` check on the next run — the same
+ * recipe {@link commentMarker} names for the `comment` mode's note, kept as
+ * its own function (rather than reused) because the two modes write to
+ * different resources and a caller may run both against the same `env`.
+ * Slugified the same way, for the same reason: interpolated next to quotes
+ * and URL-encoding it should not need escaping out of.
+ */
+export function issueMarker(env: string): string {
+  return `<!-- chant-reconcile-issue:${env.replace(/[^a-zA-Z0-9._-]+/g, "-")} -->`;
+}
+
 /** 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 (
@@ -223,6 +266,74 @@ export async function resolvePullRequestContext(
   return ctx;
 }
 
+/**
+ * The REST base a GitHub-shaped `gh api` call should target, read the same
+ * way the runner itself reads it (chant #2291). `GITHUB_API_URL` is a default
+ * environment variable every GitHub Actions *and* Forgejo Actions job carries
+ * — `https://api.github.com` on github.com, `<host>/api/v3` on GitHub
+ * Enterprise Server, and `<host>/api/v1` on Forgejo, which already advertises
+ * it correctly (confirmed on a real Forgejo 12.0.4+gitea-1.22.0 instance
+ * during INTENTIUS/choudoufu#1027: `$GITHUB_API_URL` read
+ * `http://forgejo:3000/api/v1` inside the job).
+ *
+ * Building the full URL from this rather than handing `gh api` a bare
+ * relative path (`repos/…`) is the fix itself: `gh` resolves a relative path
+ * by guessing a host-specific prefix of its own — `api.<host>` for
+ * `github.com`, `<host>/api/v3` for anything else — and that guess is `/api/v3`
+ * for a Forgejo host too, which Forgejo answers 404 for both GET and POST.
+ * Handed a full URL, `gh api` uses it verbatim and skips the guess entirely,
+ * which is what let the same `gh` binary reach Forgejo's `/api/v1` in the
+ * same session, over plain HTTP and over TLS. No Forgejo-specific branch is
+ * needed: every host in play (github.com, GHES, Forgejo) sets
+ * `GITHUB_API_URL` to the base its own `/repos/...` paths actually live
+ * under, so building the URL from it is correct everywhere `gh` already ran,
+ * not only on Forgejo.
+ */
+export function githubApiBaseFrom(env: Record<string, string | undefined>): string {
+  return env.GITHUB_API_URL?.trim().replace(/\/+$/, "") || "https://api.github.com";
+}
+
+/** The credential a GitHub- or Forgejo-shaped comment call is made with. */
+export interface CommentToken {
+  value: string;
+  /** The variable it came from, so a refusal or a log line can name it. */
+  source: string;
+}
+
+/**
+ * Resolve the token `postOrUpdateComment` sends with, most specific first
+ * (chant #2291). `gh` itself already resolves `GH_TOKEN`/`GITHUB_TOKEN`
+ * ambiently from the process environment, and the generated workflow sets
+ * both to `${{ github.token }}` for every non-`report` finding mode — on
+ * Forgejo the same way as on GitHub, and the real-instance read confirmed
+ * `github.token` is populated there and good for a 200 read and a 201 write,
+ * authored as `forgejo-actions`. So the common case needs nothing set beyond
+ * what the generator already emits.
+ *
+ * `CHANT_FORGEJO_TOKEN` is checked first for the case that ambient token
+ * cannot cover: a run posting to a Forgejo instance other than the one the
+ * job executes on, where `github.token`'s scope stops at its own instance.
+ * Resolving explicitly (rather than leaving it entirely to `gh`) also buys a
+ * named failure before the shell-out, in place of `gh`'s own opaque 401.
+ */
+export function commentTokenFrom(env: Record<string, string | undefined>): CommentToken | undefined {
+  for (const source of ["CHANT_FORGEJO_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"]) {
+    const value = env[source]?.trim();
+    if (value) return { value, source };
+  }
+  return undefined;
+}
+
+/** What a `comment`-mode step says on a pull request it has no credential for. */
+export function noCommentTokenMessage(repo: string, number: number): string {
+  return (
+    `reconcilePr mode "comment" has pull request ${repo}#${number} to post its finding on and no token to ` +
+    "post it with. GH_TOKEN or GITHUB_TOKEN, set from github.token, already covers this on a GitHub Actions " +
+    "or Forgejo Actions run — set CHANT_FORGEJO_TOKEN to post against a different instance than the one the " +
+    "job runs on. CHANT_FORGEJO_TOKEN is read first where the two must differ."
+  );
+}
+
 /**
  * Post `body` as one comment on `ctx`'s pull request, or edit the comment this
  * Op already owns there. The sticky-comment recipe the github lexicon's
@@ -230,7 +341,16 @@ export async function resolvePullRequestContext(
  * find the comment whose body starts with `marker`, PATCH it when there is
  * one, POST otherwise. `gh` ships on GitHub's hosted runners and is already
  * this activity's dependency for the issue and pull-request modes, so the
- * mode needs nothing new on the runner.
+ * mode needs nothing new on the runner — Forgejo's `act_runner` ships `gh`
+ * too, and Forgejo's `/api/v1` takes the same calls (chant #2291).
+ *
+ * Every call targets a full URL built from {@link githubApiBaseFrom} rather
+ * than the bare relative path this used before #2291 — see that function for
+ * why a bare path broke Forgejo specifically. The token is resolved
+ * explicitly via {@link commentTokenFrom} and forwarded as `GH_TOKEN`, which
+ * is a strict superset of `gh`'s own ambient resolution: same value in the
+ * common case, a named refusal instead of `gh`'s opaque 401 when neither is
+ * set.
  */
 async function postOrUpdateComment(
   ctx: PullRequestContext,
@@ -238,11 +358,16 @@ async function postOrUpdateComment(
   body: string,
   signal?: AbortSignal,
 ): Promise<string> {
-  const listPath = `repos/${ctx.repo}/issues/${ctx.number}/comments`;
+  const token = commentTokenFrom(process.env);
+  if (!token) throw new Error(noCommentTokenMessage(ctx.repo, ctx.number));
+  const env = { ...process.env, GH_TOKEN: token.value };
+
+  const base = githubApiBaseFrom(process.env);
+  const listUrl = `${base}/repos/${ctx.repo}/issues/${ctx.number}/comments`;
   const jq = `map(select(.body | startswith("${marker}"))) | .[0].id // empty`;
   const { stdout: found } = await execAsync(
-    `gh api ${shellQuote(listPath)} --paginate --jq ${shellQuote(jq)}`,
-    { signal },
+    `gh api ${shellQuote(listUrl)} --paginate --jq ${shellQuote(jq)}`,
+    { signal, env },
   );
   // `--paginate` prints one `--jq` result per page, so take the first line
   // that is an id and ignore the empty ones the other pages produce.
@@ -251,15 +376,130 @@ async function postOrUpdateComment(
 
   if (existing) {
     const { stdout } = await execAsync(
-      `gh api --method PATCH ${shellQuote(`repos/${ctx.repo}/issues/comments/${existing}`)} ` +
+      `gh api --method PATCH ${shellQuote(`${base}/repos/${ctx.repo}/issues/comments/${existing}`)} ` +
         `-f ${shellQuote(field)} --jq .html_url`,
-      { signal },
+      { signal, env },
     );
     return stdout.trim();
   }
   const { stdout } = await execAsync(
-    `gh api --method POST ${shellQuote(listPath)} -f ${shellQuote(field)} --jq .html_url`,
-    { signal },
+    `gh api --method POST ${shellQuote(listUrl)} -f ${shellQuote(field)} --jq .html_url`,
+    { signal, env },
+  );
+  return stdout.trim();
+}
+
+// ── The GitHub/GHES/Forgejo sticky issue (#2297) ────────────────────────────
+
+/**
+ * Minimal `gh` invocation shape {@link postOrUpdateGithubIssue} threads its
+ * calls through. `reconcilePr` wraps `execAsync` (carrying its own `signal`)
+ * to this shape; `lexiconUpgrade` passes its injectable `GhRunner` straight
+ * through, since the two already share the same `(cmd) => Promise<{ stdout,
+ * stderr }>` signature. One function, not two copies, because the recipe
+ * below — search, then PATCH or POST — is identical for both callers; only
+ * the issue's title/body and the marker that owns it differ.
+ */
+export type GhExec = (cmd: string) => Promise<{ stdout: string; stderr: string }>;
+
+/**
+ * Open `title`/`body` as one GitHub-shaped issue in `repo`, or edit the issue
+ * this caller already owns there (#2297) — `postOrUpdateComment`'s issue
+ * counterpart, and the GitHub/GHES/Forgejo sibling of GitLab's
+ * `postOrUpdateIssue` (#2292): find by marker, PATCH when found, POST when
+ * not, so a nightly finding carries one issue holding the current state
+ * instead of stacking a new one every run. Shared by `reconcilePr`'s own
+ * `issue` mode and `lexiconUpgrade`'s per-lexicon upgrade-status issue.
+ *
+ * Every call targets a full URL built from {@link githubApiBaseFrom}, the
+ * same as `postOrUpdateComment` (#2291) — so this reaches GitHub Enterprise
+ * Server the same way it reaches github.com.
+ *
+ * ## Why plain pagination instead of GitHub's Search API
+ *
+ * GitHub offers real server-side full-text search — `gh issue list --search`
+ * and `GET /search/issues?q=...` both use it, and chant #2297 (the issue that
+ * asked for this) names both as candidates. Neither is used here, for three
+ * reasons found while building this:
+ *
+ * 1. **Consistency.** GitHub's search index is documented as eventually
+ *    consistent: an issue this function just wrote is not guaranteed to be
+ *    findable by search immediately afterward. That is exactly the
+ *    read-after-write the sticky recipe depends on — a false "not found"
+ *    means a duplicate issue, which is the bug this activity exists to fix.
+ * 2. **The marker itself.** The hidden marker is deliberately punctuation-
+ *    heavy (`<!-- chant-reconcile-issue:app -->`) so it renders invisibly.
+ *    GitHub's search tokenizer is not documented to preserve that shape
+ *    through `in:body` matching, and a wrong query would either miss the
+ *    marker (a duplicate, the same failure mode as above) or over-match and
+ *    still need the same client-side `startswith` check this function
+ *    already does — at which point the search bought nothing but risk.
+ * 3. **Forgejo.** `gh issue list --search` and `/search/issues` are both
+ *    absent from Forgejo's API — checked against a live Forgejo instance's
+ *    own OpenAPI spec while building this: no `/search/issues`, no
+ *    `/repos/issues/search` path anywhere in it (Forgejo's own issues-list
+ *    endpoint does carry a real `q` search parameter, but that is a
+ *    different endpoint shape than GitHub's, which would mean forking this
+ *    function by forge — exactly what the `comment` path (#2291)
+ *    deliberately does not do).
+ *
+ * So this reuses the recipe `postOrUpdateComment` already proved for PR
+ * comments: list, `--paginate`, filter with `--jq` by an exact `startswith`
+ * prefix match, which is correct no matter how many pages it takes. The cost
+ * is real — a repository with many thousands of issues pays for every page
+ * on every run — and is the accepted trade-off here; narrowing further with
+ * GitHub's `creator` filter was considered and left alone, because the
+ * identity a `GH_TOKEN` posts as cannot be assumed reliably across a
+ * generated workflow and a hand-run one, and a wrong `creator` is a false
+ * negative — a duplicate — not just a slower search.
+ *
+ * ## The close decision (#2297)
+ *
+ * This never closes the issue, in either branch, matching both GitLab paths
+ * (#2256, #2292) — neither of which closes anything either. The search is
+ * scoped to `state=open` rather than `state=all`, which makes that decision
+ * concrete rather than implicit: a human closing the issue by hand, once the
+ * drift it named is actually fixed, is what tells the *next* run to open a
+ * fresh issue for a fresh finding instead of silently rewriting the closed
+ * one back open-in-substance-but-not-in-state. The alternative — searching
+ * `state=all` and reopening on write — would need this activity to guess
+ * when a finding is "resolved" with no reliable signal for that (an empty
+ * change set this run says nothing about whether the *last* finding was
+ * fixed or just not evaluated), and would turn a deliberate human "done" into
+ * something the bot silently reverses on its next run.
+ *
+ * `.pull_request == null` is filtered out of the search because GitHub's
+ * issues-list endpoint also returns pull requests, which this function must
+ * never mistake for an issue it owns.
+ */
+export async function postOrUpdateGithubIssue(
+  repo: string,
+  marker: string,
+  title: string,
+  body: string,
+  exec: GhExec,
+): Promise<string> {
+  const base = githubApiBaseFrom(process.env);
+  const listUrl = `${base}/repos/${repo}/issues?state=open`;
+  const jq =
+    'map(select((.pull_request == null) and ((.body // "") | startswith(' +
+    `"${marker}"))))` +
+    " | .[0].number // empty";
+  const { stdout: found } = await exec(`gh api ${shellQuote(listUrl)} --paginate --jq ${shellQuote(jq)}`);
+  // `--paginate` prints one `--jq` result per page, same as postOrUpdateComment.
+  const existing = found.split("\n").map((l) => l.trim()).find((l) => /^\d+$/.test(l));
+  const titleField = shellQuote(`title=${title}`);
+  const bodyField = shellQuote(`body=${marker}\n\n${body}`);
+
+  if (existing) {
+    const { stdout } = await exec(
+      `gh api --method PATCH ${shellQuote(`${base}/repos/${repo}/issues/${existing}`)} ` +
+        `-f ${titleField} -f ${bodyField} --jq .html_url`,
+    );
+    return stdout.trim();
+  }
+  const { stdout } = await exec(
+    `gh api --method POST ${shellQuote(`${base}/repos/${repo}/issues`)} -f ${titleField} -f ${bodyField} --jq .html_url`,
   );
   return stdout.trim();
 }
@@ -330,6 +570,54 @@ export function mergeRequestContextFrom(
   };
 }
 
+/**
+ * The GitLab project an `issue`-mode run opens or updates its issue on (#2292),
+ * as any GitLab CI job knows it — the counterpart of {@link
+ * mergeRequestContextFrom} for a mode that needs no merge request.
+ */
+export interface GitlabProjectContext {
+  /** REST v4 base, from `CI_API_V4_URL` or derived from `CI_SERVER_URL`. */
+  api: string;
+  /** The project holding the issue — its numeric id, or a `group/project` path. */
+  project: string;
+  /** `group/project`, for a human-readable result. */
+  path?: string;
+  /** The project's web URL, used to build the issue's own URL. */
+  webUrl?: string;
+}
+
+/**
+ * Derive the GitLab project an `issue`-mode run is in, from the job's own CI
+ * variables. Pure — exported for testing, and the whole forge detection:
+ * `CI_PROJECT_ID` is set on every GitLab CI job, merge request or not, and
+ * nothing outside GitLab CI sets it — a GitHub Actions run never reaches this
+ * branch. Unlike {@link mergeRequestContextFrom}, no `CI_MERGE_REQUEST_IID`
+ * is required, since `issue` mode's whole point is a cron trigger that has
+ * none.
+ *
+ * Returns undefined rather than throwing, so the caller owns the fallback:
+ * a run with no GitLab signal falls through to `gh issue create`.
+ */
+export function gitlabProjectContextFrom(
+  env: Record<string, string | undefined>,
+): GitlabProjectContext | undefined {
+  const project = env.CI_PROJECT_ID?.trim();
+  if (!project) 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 path = env.CI_PROJECT_PATH?.trim();
+  const webUrl = env.CI_PROJECT_URL?.trim();
+  return {
+    api,
+    project,
+    ...(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`. */
@@ -377,6 +665,16 @@ export function noGitlabNoteTokenMessage(iid: number): string {
   );
 }
 
+/** What an `issue`-mode step says on a GitLab project it has no credential for (#2292). */
+export function noGitlabIssueTokenMessage(project: string): string {
+  return (
+    `reconcilePr mode "issue" wants to open or update an issue on GitLab project ${project} and has no ` +
+    "token to do 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 issues 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;
@@ -484,6 +782,93 @@ async function postOrUpdateNote(
     : `${endpoint}/${note.id}`;
 }
 
+// ── The GitLab issue (#2292) ─────────────────────────────────────────────
+
+/** One GitLab issue, as much of it as this activity reads. */
+interface GitlabIssue {
+  iid: number;
+  description?: string;
+}
+
+/** GitLab's REST path for a project's issues. */
+function issuesEndpoint(ctx: GitlabProjectContext): string {
+  return `${ctx.api}/projects/${encodeURIComponent(ctx.project)}/issues`;
+}
+
+/**
+ * Find the issue this Op already owns in `ctx`'s project, by the same hidden
+ * marker `findOwnedNote` looks a merge-request note up by: the marker is the
+ * description's first line and the match is a prefix.
+ *
+ * `search`/`in=description` narrows the request server-side to issues whose
+ * description contains the marker, rather than paging every issue the
+ * project has ever opened — a long-lived project accumulates issues the way
+ * an active merge request accumulates notes, and the marker is exact text a
+ * full-text search matches reliably. The `startswith` check after the fetch
+ * still decides ownership, the same as the note lookup, since `search` finds
+ * the marker anywhere in the field and only a match at the very start is
+ * this Op's own issue rather than one that happens to quote it.
+ *
+ * Paged the way GitLab pages, following the `x-next-page` response header —
+ * see {@link findOwnedNote} for why a bounded loop rather than a guessed page
+ * count.
+ */
+async function findOwnedIssue(
+  ctx: GitlabProjectContext,
+  token: GitlabNoteToken,
+  marker: string,
+  signal?: AbortSignal,
+): Promise<number | undefined> {
+  const endpoint = issuesEndpoint(ctx);
+  const MAX_PAGES = 50;
+  for (let page = 1; page <= MAX_PAGES; page++) {
+    const res = await gitlabRequest(
+      `${endpoint}?per_page=100&page=${page}&search=${encodeURIComponent(marker)}&in=description`,
+      token,
+      { method: "GET" },
+      signal,
+    );
+    const issues = (await res.json()) as GitlabIssue[];
+    const owned = issues.find((issue) => (issue.description ?? "").startsWith(marker));
+    if (owned) return owned.iid;
+    const next = res.headers.get("x-next-page")?.trim();
+    if (!next) return undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Open `title`/`body` as one issue in `ctx`'s project, or edit the issue this
+ * Op already owns there — {@link postOrUpdateNote}'s issue counterpart, and
+ * the same recipe: find by marker, PUT when there is one, POST when there is
+ * not, so a cron Op that finds drift every night carries one issue holding
+ * the current finding rather than a new one each run (#2292).
+ *
+ * `title` is written on every call, POST or PUT, so the issue's headline
+ * stays current (e.g. an entry count) even though only the description's
+ * marker is what makes the issue findable again.
+ */
+async function postOrUpdateIssue(
+  ctx: GitlabProjectContext,
+  token: GitlabNoteToken,
+  marker: string,
+  title: string,
+  body: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  const endpoint = issuesEndpoint(ctx);
+  const existing = await findOwnedIssue(ctx, token, marker, signal);
+  const payload = JSON.stringify({ title, description: `${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 issue = (await res.json()) as GitlabIssue;
+  // GitLab does return a `web_url` on an issue payload, unlike a note, but
+  // building it from the project's own web URL keeps this symmetric with
+  // `postOrUpdateNote` and needs no extra field pinned in tests.
+  return ctx.webUrl ? `${ctx.webUrl}/-/issues/${issue.iid}` : `${endpoint}/${issue.iid}`;
+}
+
 /**
  * Map a `chant lifecycle plan --json` ChangeSet to reconcile entries, dropping
  * `noop` entries (nothing to reconcile). Pure — exported for testing.
@@ -515,16 +900,24 @@ async function derivePlanEntries(
  * Reconcile activity: turn regenerated TypeScript into a reviewable artifact.
  *
  * - `report` — return the summary only; no git, no network.
- * - `issue` — open a GitHub issue describing the drift (no code change).
+ * - `issue` — open or edit one issue describing the drift (no code change).
+ *   On a GitHub Actions or Forgejo Actions job, or GitHub Enterprise Server,
+ *   the OPEN issue already carrying this Op's hidden marker is edited in
+ *   place and a new one opened only when there is none (#2297). On a GitLab
+ *   CI job (any trigger — the point of this mode is a cron run that has no
+ *   merge request), the same recipe against one GitLab issue (#2292). Neither
+ *   branch ever closes the issue itself — see {@link postOrUpdateGithubIssue}
+ *   for that decision and why.
  * - `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), 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.
+ *   stacking a new one (#2231) — on GitHub and on Forgejo alike (#2291), the
+ *   same GitHub-shaped `issues/{n}/comments` calls against each host's own
+ *   API base — 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 and
+ *   Forgejo; 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.
@@ -549,8 +942,38 @@ export async function reconcilePr(args: ReconcilePrArgs, signal?: AbortSignal):
   }
 
   if (mode === "issue") {
+    const marker = args.marker ?? issueMarker(args.env);
+
+    // GitLab first, because its check is the narrow one: `CI_PROJECT_ID` is
+    // set on every GitLab CI job, and nothing outside GitLab CI sets it
+    // (#2292) — see `gitlabProjectContextFrom`.
+    const project = gitlabProjectContextFrom(process.env);
+    if (project) {
+      const token = gitlabNoteTokenFrom(process.env);
+      if (!token) throw new Error(noGitlabIssueTokenMessage(project.project));
+      const issueUrl = await postOrUpdateIssue(project, token, marker, title, summary, signal);
+      return { mode, summary, entries, issueUrl };
+    }
+
+    // GitHub, GHES, or Forgejo next: any job that ran under GitHub Actions or
+    // Forgejo Actions carries GITHUB_REPOSITORY (#2297) — see
+    // postOrUpdateGithubIssue's own doc comment for the search mechanism and
+    // the close decision.
+    const repo = process.env.GITHUB_REPOSITORY;
+    if (repo) {
+      const issueUrl = await postOrUpdateGithubIssue(repo, marker, title, summary, (cmd) =>
+        execAsync(cmd, { signal }),
+      );
+      return { mode, summary, entries, issueUrl };
+    }
+
+    // Outside any known CI job (a local or manual invocation): fall back to
+    // gh's own ambient repo detection, unchanged from before #2297. The
+    // marker is still written here — it costs nothing, and means a later CI
+    // run of the same Op finds and edits this issue instead of opening a
+    // second one.
     const { stdout } = await execAsync(
-      `gh issue create --title ${shellQuote(title)} --body ${shellQuote(summary)}`,
+      `gh issue create --title ${shellQuote(title)} --body ${shellQuote(`${marker}\n\n${summary}`)}`,
       { signal },
     );
     return { mode, summary, entries, issueUrl: stdout.trim() };