@intentius/chant-lexicon-forgejo 0.124.54 → 0.124.56

package/dist/components/ci-jobs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ci-jobs.d.ts","sourceRoot":"","sources":["../../src/components/ci-jobs.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iEAAiE,CAAC;AAC3G,OAAO,EAA2B,KAAK,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEjF,kEAAkE;AAClE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAElH;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQ5F;AAED,0FAA0F;AAC1F,wBAAgB,wBAAwB,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,EAAE,CAQ1E;AAED,mHAAmH;AACnH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAOlF;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe;IAAK,iBAAiB;CAAqC,CAAC;AAExF;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,mBAAmB,EAAE,OAAO,EAAE,qBAAqB,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,mBAAmB,CAanI"}
+{"version":3,"file":"ci-jobs.d.ts","sourceRoot":"","sources":["../../src/components/ci-jobs.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iEAAiE,CAAC;AAC3G,OAAO,EAA2B,KAAK,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEjF,kEAAkE;AAClE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAElH;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQ5F;AAED,0FAA0F;AAC1F,wBAAgB,wBAAwB,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,EAAE,CAQ1E;AAED,mHAAmH;AACnH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAOlF;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe;IAAK,iBAAiB;CAAqC,CAAC;AAExF;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,mBAAmB,EAAE,OAAO,EAAE,qBAAqB,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,mBAAmB,CAcnI"}

package/dist/components/ci-jobs.js

@@ -68,5 +68,6 @@ export function forgejoWorkflowDoc(doc, dialect, header) {
         jobsDoc: forgejoize(withoutEnvironment(doc.jobsDoc), dialect),
         ...(doc.gatedNoticeDoc ? { gatedNoticeDoc: forgejoize(doc.gatedNoticeDoc, dialect) } : {}),
         ...(doc.reviewNoteDoc ? { reviewNoteDoc: forgejoize(doc.reviewNoteDoc, dialect) } : {}),
+        ...(doc.agentDoc ? { agentDoc: forgejoize(doc.agentDoc, dialect) } : {}),
     };
 }

package/dist/components/control-pipeline.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The control repo's own workflow (#4568) on Forgejo: github's document
+ * (`controlGithubDoc`) with the Forgejo dialect applied, the way
+ * ./generate-pipeline.ts reuses github's pipeline. Forgejo has no
+ * `repository_dispatch`, so a member's dispatch is a workflow dispatch of
+ * this file by name.
+ */
+import { type ControlPipelineFile, type ControlPipelineOptions } from "@intentius/chant-lexicon-github/components/control-pipeline";
+import type { ForgejoDialectOptions } from "../dialect.js";
+/** The control repo's workflow on Forgejo: `.forgejo/workflows/<product>-dependents.yml`. */
+export declare function generateControlPipeline(options?: ControlPipelineOptions, dialect?: ForgejoDialectOptions): ControlPipelineFile;
+//# sourceMappingURL=control-pipeline.d.ts.map

package/dist/components/control-pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/control-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC5B,MAAM,6DAA6D,CAAC;AAErE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAGxD,6FAA6F;AAC7F,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,sBAA2B,EAAE,OAAO,GAAE,qBAA0B,GAAG,mBAAmB,CAQtI"}

package/dist/components/control-pipeline.js

@@ -0,0 +1,20 @@
+/**
+ * The control repo's own workflow (#4568) on Forgejo: github's document
+ * (`controlGithubDoc`) with the Forgejo dialect applied, the way
+ * ./generate-pipeline.ts reuses github's pipeline. Forgejo has no
+ * `repository_dispatch`, so a member's dispatch is a workflow dispatch of
+ * this file by name.
+ */
+import { controlGithubDoc, } from "@intentius/chant-lexicon-github/components/control-pipeline";
+import { emitWorkflowYAML } from "@intentius/chant-lexicon-github/components/ci-jobs";
+import { forgejoize } from "./ci-jobs.js";
+/** The control repo's workflow on Forgejo: `.forgejo/workflows/<product>-dependents.yml`. */
+export function generateControlPipeline(options = {}, dialect = {}) {
+    const { doc, path, notes } = controlGithubDoc("forgejo", options);
+    const content = emitWorkflowYAML({
+        ...doc,
+        on: forgejoize(doc.on, dialect),
+        jobsDoc: forgejoize(doc.jobsDoc, dialect),
+    });
+    return { path, content, notes };
+}

package/dist/components/generate-op-pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-op-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsFG;AAMH,OAAO,KAAK,EACV,wBAAwB,EACxB,gBAAgB,EAChB,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAGxD;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,wBAA6B,EACtC,cAAc,GAAE,qBAA0B,GACzC,gBAAgB,CAmBlB"}
+{"version":3,"file":"generate-op-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsFG;AAMH,OAAO,KAAK,EACV,wBAAwB,EACxB,gBAAgB,EAChB,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAGxD;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,wBAA6B,EACtC,cAAc,GAAE,qBAA0B,GACzC,gBAAgB,CAqBlB"}

package/dist/components/generate-op-pipeline.js

@@ -86,6 +86,7 @@
  * sibling Op's job receives.
  */
 import { buildGithubOpPipelineDocs, emitOpPipelineYAML, } from "@intentius/chant-lexicon-github/components/generate-op-pipeline";
+import { assertRunnerLabels } from "@intentius/chant/ci-jobs";
 import { droppedEnvironmentHeader, forgejoWorkflowDoc } from "./ci-jobs.js";
 /**
  * Synthesize one `.forgejo/workflows/*.yml` per scheduled Op. Reuses github's
@@ -100,7 +101,10 @@ export function generateForgejoOpPipeline(ops, options = {}, dialectOptions = {}
     // `findingMode: "comment"` used to be refused by name here (#2231), and
     // `findingMode: "issue"` from #2332 to #2351. Neither is now: both post
     // through the Forgejo client — see the module doc above.
-    const { files, jobs } = buildGithubOpPipelineDocs(ops, options);
+    // #4616: a spec's runner is a label or a list of labels here.
+    for (const spec of ops)
+        assertRunnerLabels(`Scheduled Op "${spec.name}"`, "runner", spec.runner, "Forgejo");
+    const { files, jobs } = buildGithubOpPipelineDocs(ops, options, "forgejo");
     return {
         // One file per spec, in spec order, which is what lets the header below
         // read its Op's own `environment` off the input by position.

package/dist/components/generate-op-waves-pipeline.d.ts

@@ -12,8 +12,8 @@
  * so it dispatches the waves workflow again on its branch, with the
  * `CHANT_FORGE_TOKEN` secret (a token with the `write:repository` scope).
  *
- * A `pr-review` wave (#3684) gets `<name>-plans.yml` on pull requests, as on
- * GitHub. Forgejo's job token reads reviews with no permission to ask for.
+ * A `pr-review` wave (#3684), or a `pull-request` wave (#4630), gets
+ * `<name>-plans.yml` on pull requests, as on GitHub. Forgejo's job token reads reviews with no permission to ask for.
  *
  * `runner` and a wave's `jobs` (#3914) render as on GitHub, with two limits:
  * a runner is a label or a list of labels (a GitHub runner group is a spec
@@ -21,6 +21,10 @@
  * none to put in front of it. A job with id tokens keeps `permissions:
  * id-token: write`, the one scope the dialect leaves, and reads each audience
  * from `<NAME>_AUDIENCE` when it requests its token.
+ *
+ * The apply-job guard (#4624) starts each wave job as on GitHub, with the
+ * forge set to Forgejo: it checks the ref and, for a `self-hosted` label,
+ * the runner, and no forge environment, since Forgejo has none.
  */
 import type { OpWavesSpec } from "@intentius/chant/op/op-waves";
 import type { OpWavesPipelineOptions, OpWavesPipelineResult } from "@intentius/chant/lexicon";

package/dist/components/generate-op-waves-pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-op-waves-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-waves-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAEhE,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAC9F,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAGxD,6EAA6E;AAC7E,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,sBAAsB,EAC/B,cAAc,GAAE,qBAA0B,GACzC,qBAAqB,CAiBvB"}
+{"version":3,"file":"generate-op-waves-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-waves-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAEhE,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAC9F,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAGxD,6EAA6E;AAC7E,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,sBAAsB,EAC/B,cAAc,GAAE,qBAA0B,GACzC,qBAAqB,CAiBvB"}

package/dist/components/generate-op-waves-pipeline.js

@@ -12,8 +12,8 @@
  * so it dispatches the waves workflow again on its branch, with the
  * `CHANT_FORGE_TOKEN` secret (a token with the `write:repository` scope).
  *
- * A `pr-review` wave (#3684) gets `<name>-plans.yml` on pull requests, as on
- * GitHub. Forgejo's job token reads reviews with no permission to ask for.
+ * A `pr-review` wave (#3684), or a `pull-request` wave (#4630), gets
+ * `<name>-plans.yml` on pull requests, as on GitHub. Forgejo's job token reads reviews with no permission to ask for.
  *
  * `runner` and a wave's `jobs` (#3914) render as on GitHub, with two limits:
  * a runner is a label or a list of labels (a GitHub runner group is a spec
@@ -21,6 +21,10 @@
  * none to put in front of it. A job with id tokens keeps `permissions:
  * id-token: write`, the one scope the dialect leaves, and reads each audience
  * from `<NAME>_AUDIENCE` when it requests its token.
+ *
+ * The apply-job guard (#4624) starts each wave job as on GitHub, with the
+ * forge set to Forgejo: it checks the ref and, for a `self-hosted` label,
+ * the runner, and no forge environment, since Forgejo has none.
  */
 import { buildGithubOpWavesDoc } from "@intentius/chant-lexicon-github/components/generate-op-waves-pipeline";
 import { emitOpPipelineYAML } from "@intentius/chant-lexicon-github/components/generate-op-pipeline";
@@ -29,7 +33,7 @@ import { droppedWaveEnvironmentsHeader, FORGE_TOKEN_ENV, forgejoWorkflowDoc } fr
 /** Render an Op waves spec as one Forgejo Actions workflow, `<name>.yml`. */
 export function generateForgejoOpWavesPipeline(spec, options, dialectOptions = {}) {
     assertForgejoWaves(spec);
-    const { doc, jobs, resumeDoc, plansDoc } = buildGithubOpWavesDoc(spec, options);
+    const { doc, jobs, resumeDoc, plansDoc } = buildGithubOpWavesDoc(spec, options, { forge: "forgejo" });
     const dropped = spec.waves.filter((w) => w.environment).map((w) => `${w.name} -> ${w.environment.name}`);
     const header = dropped.length > 0 ? droppedWaveEnvironmentsHeader(dropped) : undefined;
     const files = [{ name: `${spec.name}.yml`, yaml: emitOpPipelineYAML(forgejoWorkflowDoc(doc, dialectOptions, header)) }];

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "0a6dc57e7d8145e558ff06623c2d0e382f169c0dd47004d1bec2807e7c424c08",
+    "manifest.json": "d8927356783df4ae21c431e0a016299273a031fecc05ead9df07f900b57ed4c7",
     "meta.json": "44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
     "types/index.d.ts": "66204549b2a864ab5489e3f02c1878e73ab4b3c9d938cfb480b66f71543a43de",
     "rules/delegate-to-github.ts": "1060cda40f4b73d6cca3ba3fa13b80b4886147d4034c88584c2d80c5510dbe5e",
@@ -9,5 +9,5 @@
     "rules/wfj011.ts": "fcb8bf6685d744af20ad804ce929488257995c74b9a3353b2eacae3768d1c83e",
     "skills/chant-forgejo.md": "f28d7fb69fb1cfd992496ef41fda0ea5ccd54a29b84ea1c501a44f6a3992c4d5"
   },
-  "composite": "3011e602acaca2080397cd441b1153f053cbc914e39da45949674d2055d02a37"
+  "composite": "7b0449ca0d3675a7e8c15a30fc85f3de807f6eb7eb538536867e77edd16ee133"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "forgejo",
-  "version": "0.124.54",
+  "version": "0.124.56",
   "chantVersion": ">=0.1.0",
   "namespace": "Forgejo",
   "intrinsics": [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-forgejo",
-  "version": "0.124.54",
+  "version": "0.124.56",
   "description": "Forgejo / Codeberg / Gitea Actions lexicon for chant — a thin GitHub Actions dialect",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -54,8 +54,8 @@
   },
   "peerDependencies": {
     "zod": "^4.3.6",
-    "@intentius/chant": "^0.124.54",
-    "@intentius/chant-lexicon-github": "^0.124.54"
+    "@intentius/chant": "^0.124.56",
+    "@intentius/chant-lexicon-github": "^0.124.56"
   },
   "scripts": {
     "generate": "tsx src/codegen/generate-cli.ts",

package/src/components/__golden__/op-waves-jobs.yml

@@ -15,6 +15,10 @@ jobs:
     runs-on: plan
     container: node:22
     steps:
+      - name: Check the job runs where the spec set it to run
+        env:
+          CHANT_JOB_GUARD: '{"forge":"forgejo","job":"wave 1 (dev) of migrations","branches":["main"]}'
+        run: '(cd / && node -e ''"use strict";const E=process.env,A="chant-check-job";const shown=(v)=>v===undefined||v===null||v===""?"none":v;const fail=(m)=>{console.error("check-job: "+m);process.exit(9)};let x;try{x=JSON.parse(E.CHANT_JOB_GUARD||"")}catch(e){fail("CHANT_JOB_GUARD is not JSON")}if(!x||!["github","gitlab","forgejo"].includes(x.forge)||!Array.isArray(x.branches))fail("CHANT_JOB_GUARD is not a guard spec");const tags=(r)=>{if(r===undefined)return undefined;const t=r.trim();if(t.startsWith("[")){try{const v=JSON.parse(t);if(Array.isArray(v))return v.map(String)}catch(e){}}return t===""?[]:t.split(",").map((s)=>s.trim()).filter((s)=>s!=="")};const claimsOf=(tok)=>{const p=tok.split(".")[1];if(!p)throw new Error("the forge\u0027s OIDC token is not a JWT");const c=JSON.parse(Buffer.from(p.replace(/-/g,"+").replace(/_/g,"/"),"base64").toString("utf-8"));if(!c||typeof c!=="object")throw new Error("the forge\u0027s OIDC token has no claims");return c};async function seenOf(){if(x.forge==="gitlab")return{forgeEnvironment:E.CI_ENVIRONMENT_NAME||null,ref:E.CI_COMMIT_REF_NAME,refProtected:E.CI_COMMIT_REF_PROTECTED,runnerTags:tags(E.CI_RUNNER_TAGS)};const s={ref:E.GITHUB_REF};let c;if(x.forge==="github"&&x.forgeEnvironment!==undefined){try{if(!E.ACTIONS_ID_TOKEN_REQUEST_URL||!E.ACTIONS_ID_TOKEN_REQUEST_TOKEN)throw new Error("the job may request no OIDC token (no ACTIONS_ID_TOKEN_REQUEST_URL); it needs the id-token: write permission");const r=await fetch(E.ACTIONS_ID_TOKEN_REQUEST_URL+"&audience="+encodeURIComponent(A),{headers:{authorization:"bearer "+E.ACTIONS_ID_TOKEN_REQUEST_TOKEN}});if(!r.ok)throw new Error("the OIDC token request answered "+r.status);const v=(await r.json()).value;if(typeof v!=="string")throw new Error("the OIDC token request answered no token");c=claimsOf(v);s.forgeEnvironment=typeof c.environment==="string"&&c.environment!==""?c.environment:null}catch(e){s.forgeEnvironmentError=e&&e.message?e.message:String(e)}}const run=c&&typeof c.runner_environment==="string"?c.runner_environment:E.RUNNER_ENVIRONMENT;if(run)s.runnerEnvironment=run;return s}seenOf().then((s)=>{const P=[],C=[],S=[];const fe=x.forgeEnvironment;if(x.forge==="forgejo")S.push("forge environment (Forgejo has none)");else if(fe!==undefined){if(s.forgeEnvironmentError!==undefined)P.push("forge environment: expected "+fe+", and it could not be read: "+s.forgeEnvironmentError);else if(s.forgeEnvironment!==fe)P.push("forge environment: expected "+fe+", found "+shown(s.forgeEnvironment));else C.push("forge environment "+fe)}const b=x.branches.filter((v)=>v!=="");if(b.length===0)P.push("ref: the job names no branch to run from");else if(x.forge==="gitlab"){if(!s.ref||!b.includes(s.ref))P.push("ref: expected "+b.join(" or ")+", found "+shown(s.ref));else C.push("ref "+s.ref);if(s.refProtected!=="true")P.push("ref: expected a protected ref (CI_COMMIT_REF_PROTECTED true), found "+shown(s.refProtected));else C.push("protected ref")}else{const refs=b.map((v)=>"refs/heads/"+v);if(!s.ref||!refs.includes(s.ref))P.push("ref: expected "+refs.join(" or ")+", found "+shown(s.ref));else C.push("ref "+s.ref)}if(x.forge==="gitlab"){const w=x.runnerTags||[];if(w.length>0){const h=s.runnerTags;const miss=w.filter((t)=>!(h||[]).includes(t));if(h===undefined)P.push("runner: expected tags "+w.join(", ")+", and the job has no CI_RUNNER_TAGS");else if(miss.length>0)P.push("runner: expected tags "+w.join(", ")+", found "+(h.length?h.join(", "):"none"));else C.push("runner tags "+w.join(", "))}}else if(x.selfHosted){if(s.runnerEnvironment===undefined)S.push("runner (the runner says nothing about itself: no RUNNER_ENVIRONMENT)");else if(s.runnerEnvironment!=="self-hosted")P.push("runner: expected self-hosted, found "+s.runnerEnvironment);else C.push("self-hosted runner")}const at=(x.product||"chant")+" check-job: "+x.job;if(P.length>0){for(const p of P)console.error(at+": "+p);console.error(at+": this job does not run where the spec set it to run, so it stops before any credential is taken or code checked out");process.exit(9)}console.log(at+": "+(C.length?C.join(", "):"nothing to check")+(S.length?"; not checked: "+S.join(", "):""))}).catch((e)=>fail(e&&e.message?e.message:String(e)));'')'
       - uses: https://code.forgejo.org/actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
@@ -34,6 +38,10 @@ jobs:
     if: '!cancelled()'
     container: node:22
     steps:
+      - name: Check the job runs where the spec set it to run
+        env:
+          CHANT_JOB_GUARD: '{"forge":"forgejo","job":"the deciding job of wave 2 (prod) of migrations","branches":["main"]}'
+        run: '(cd / && node -e ''"use strict";const E=process.env,A="chant-check-job";const shown=(v)=>v===undefined||v===null||v===""?"none":v;const fail=(m)=>{console.error("check-job: "+m);process.exit(9)};let x;try{x=JSON.parse(E.CHANT_JOB_GUARD||"")}catch(e){fail("CHANT_JOB_GUARD is not JSON")}if(!x||!["github","gitlab","forgejo"].includes(x.forge)||!Array.isArray(x.branches))fail("CHANT_JOB_GUARD is not a guard spec");const tags=(r)=>{if(r===undefined)return undefined;const t=r.trim();if(t.startsWith("[")){try{const v=JSON.parse(t);if(Array.isArray(v))return v.map(String)}catch(e){}}return t===""?[]:t.split(",").map((s)=>s.trim()).filter((s)=>s!=="")};const claimsOf=(tok)=>{const p=tok.split(".")[1];if(!p)throw new Error("the forge\u0027s OIDC token is not a JWT");const c=JSON.parse(Buffer.from(p.replace(/-/g,"+").replace(/_/g,"/"),"base64").toString("utf-8"));if(!c||typeof c!=="object")throw new Error("the forge\u0027s OIDC token has no claims");return c};async function seenOf(){if(x.forge==="gitlab")return{forgeEnvironment:E.CI_ENVIRONMENT_NAME||null,ref:E.CI_COMMIT_REF_NAME,refProtected:E.CI_COMMIT_REF_PROTECTED,runnerTags:tags(E.CI_RUNNER_TAGS)};const s={ref:E.GITHUB_REF};let c;if(x.forge==="github"&&x.forgeEnvironment!==undefined){try{if(!E.ACTIONS_ID_TOKEN_REQUEST_URL||!E.ACTIONS_ID_TOKEN_REQUEST_TOKEN)throw new Error("the job may request no OIDC token (no ACTIONS_ID_TOKEN_REQUEST_URL); it needs the id-token: write permission");const r=await fetch(E.ACTIONS_ID_TOKEN_REQUEST_URL+"&audience="+encodeURIComponent(A),{headers:{authorization:"bearer "+E.ACTIONS_ID_TOKEN_REQUEST_TOKEN}});if(!r.ok)throw new Error("the OIDC token request answered "+r.status);const v=(await r.json()).value;if(typeof v!=="string")throw new Error("the OIDC token request answered no token");c=claimsOf(v);s.forgeEnvironment=typeof c.environment==="string"&&c.environment!==""?c.environment:null}catch(e){s.forgeEnvironmentError=e&&e.message?e.message:String(e)}}const run=c&&typeof c.runner_environment==="string"?c.runner_environment:E.RUNNER_ENVIRONMENT;if(run)s.runnerEnvironment=run;return s}seenOf().then((s)=>{const P=[],C=[],S=[];const fe=x.forgeEnvironment;if(x.forge==="forgejo")S.push("forge environment (Forgejo has none)");else if(fe!==undefined){if(s.forgeEnvironmentError!==undefined)P.push("forge environment: expected "+fe+", and it could not be read: "+s.forgeEnvironmentError);else if(s.forgeEnvironment!==fe)P.push("forge environment: expected "+fe+", found "+shown(s.forgeEnvironment));else C.push("forge environment "+fe)}const b=x.branches.filter((v)=>v!=="");if(b.length===0)P.push("ref: the job names no branch to run from");else if(x.forge==="gitlab"){if(!s.ref||!b.includes(s.ref))P.push("ref: expected "+b.join(" or ")+", found "+shown(s.ref));else C.push("ref "+s.ref);if(s.refProtected!=="true")P.push("ref: expected a protected ref (CI_COMMIT_REF_PROTECTED true), found "+shown(s.refProtected));else C.push("protected ref")}else{const refs=b.map((v)=>"refs/heads/"+v);if(!s.ref||!refs.includes(s.ref))P.push("ref: expected "+refs.join(" or ")+", found "+shown(s.ref));else C.push("ref "+s.ref)}if(x.forge==="gitlab"){const w=x.runnerTags||[];if(w.length>0){const h=s.runnerTags;const miss=w.filter((t)=>!(h||[]).includes(t));if(h===undefined)P.push("runner: expected tags "+w.join(", ")+", and the job has no CI_RUNNER_TAGS");else if(miss.length>0)P.push("runner: expected tags "+w.join(", ")+", found "+(h.length?h.join(", "):"none"));else C.push("runner tags "+w.join(", "))}}else if(x.selfHosted){if(s.runnerEnvironment===undefined)S.push("runner (the runner says nothing about itself: no RUNNER_ENVIRONMENT)");else if(s.runnerEnvironment!=="self-hosted")P.push("runner: expected self-hosted, found "+s.runnerEnvironment);else C.push("self-hosted runner")}const at=(x.product||"chant")+" check-job: "+x.job;if(P.length>0){for(const p of P)console.error(at+": "+p);console.error(at+": this job does not run where the spec set it to run, so it stops before any credential is taken or code checked out");process.exit(9)}console.log(at+": "+(C.length?C.join(", "):"nothing to check")+(S.length?"; not checked: "+S.join(", "):""))}).catch((e)=>fail(e&&e.message?e.message:String(e)));'')'
       - uses: https://code.forgejo.org/actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
@@ -70,6 +78,10 @@ jobs:
       REGION: us
       CLOUD_TOKEN_AUDIENCE: us.example
     steps:
+      - name: Check the job runs where the spec set it to run
+        env:
+          CHANT_JOB_GUARD: '{"forge":"forgejo","job":"job group us of wave 2 (prod) of migrations","branches":["main"],"selfHosted":true}'
+        run: '(cd / && node -e ''"use strict";const E=process.env,A="chant-check-job";const shown=(v)=>v===undefined||v===null||v===""?"none":v;const fail=(m)=>{console.error("check-job: "+m);process.exit(9)};let x;try{x=JSON.parse(E.CHANT_JOB_GUARD||"")}catch(e){fail("CHANT_JOB_GUARD is not JSON")}if(!x||!["github","gitlab","forgejo"].includes(x.forge)||!Array.isArray(x.branches))fail("CHANT_JOB_GUARD is not a guard spec");const tags=(r)=>{if(r===undefined)return undefined;const t=r.trim();if(t.startsWith("[")){try{const v=JSON.parse(t);if(Array.isArray(v))return v.map(String)}catch(e){}}return t===""?[]:t.split(",").map((s)=>s.trim()).filter((s)=>s!=="")};const claimsOf=(tok)=>{const p=tok.split(".")[1];if(!p)throw new Error("the forge\u0027s OIDC token is not a JWT");const c=JSON.parse(Buffer.from(p.replace(/-/g,"+").replace(/_/g,"/"),"base64").toString("utf-8"));if(!c||typeof c!=="object")throw new Error("the forge\u0027s OIDC token has no claims");return c};async function seenOf(){if(x.forge==="gitlab")return{forgeEnvironment:E.CI_ENVIRONMENT_NAME||null,ref:E.CI_COMMIT_REF_NAME,refProtected:E.CI_COMMIT_REF_PROTECTED,runnerTags:tags(E.CI_RUNNER_TAGS)};const s={ref:E.GITHUB_REF};let c;if(x.forge==="github"&&x.forgeEnvironment!==undefined){try{if(!E.ACTIONS_ID_TOKEN_REQUEST_URL||!E.ACTIONS_ID_TOKEN_REQUEST_TOKEN)throw new Error("the job may request no OIDC token (no ACTIONS_ID_TOKEN_REQUEST_URL); it needs the id-token: write permission");const r=await fetch(E.ACTIONS_ID_TOKEN_REQUEST_URL+"&audience="+encodeURIComponent(A),{headers:{authorization:"bearer "+E.ACTIONS_ID_TOKEN_REQUEST_TOKEN}});if(!r.ok)throw new Error("the OIDC token request answered "+r.status);const v=(await r.json()).value;if(typeof v!=="string")throw new Error("the OIDC token request answered no token");c=claimsOf(v);s.forgeEnvironment=typeof c.environment==="string"&&c.environment!==""?c.environment:null}catch(e){s.forgeEnvironmentError=e&&e.message?e.message:String(e)}}const run=c&&typeof c.runner_environment==="string"?c.runner_environment:E.RUNNER_ENVIRONMENT;if(run)s.runnerEnvironment=run;return s}seenOf().then((s)=>{const P=[],C=[],S=[];const fe=x.forgeEnvironment;if(x.forge==="forgejo")S.push("forge environment (Forgejo has none)");else if(fe!==undefined){if(s.forgeEnvironmentError!==undefined)P.push("forge environment: expected "+fe+", and it could not be read: "+s.forgeEnvironmentError);else if(s.forgeEnvironment!==fe)P.push("forge environment: expected "+fe+", found "+shown(s.forgeEnvironment));else C.push("forge environment "+fe)}const b=x.branches.filter((v)=>v!=="");if(b.length===0)P.push("ref: the job names no branch to run from");else if(x.forge==="gitlab"){if(!s.ref||!b.includes(s.ref))P.push("ref: expected "+b.join(" or ")+", found "+shown(s.ref));else C.push("ref "+s.ref);if(s.refProtected!=="true")P.push("ref: expected a protected ref (CI_COMMIT_REF_PROTECTED true), found "+shown(s.refProtected));else C.push("protected ref")}else{const refs=b.map((v)=>"refs/heads/"+v);if(!s.ref||!refs.includes(s.ref))P.push("ref: expected "+refs.join(" or ")+", found "+shown(s.ref));else C.push("ref "+s.ref)}if(x.forge==="gitlab"){const w=x.runnerTags||[];if(w.length>0){const h=s.runnerTags;const miss=w.filter((t)=>!(h||[]).includes(t));if(h===undefined)P.push("runner: expected tags "+w.join(", ")+", and the job has no CI_RUNNER_TAGS");else if(miss.length>0)P.push("runner: expected tags "+w.join(", ")+", found "+(h.length?h.join(", "):"none"));else C.push("runner tags "+w.join(", "))}}else if(x.selfHosted){if(s.runnerEnvironment===undefined)S.push("runner (the runner says nothing about itself: no RUNNER_ENVIRONMENT)");else if(s.runnerEnvironment!=="self-hosted")P.push("runner: expected self-hosted, found "+s.runnerEnvironment);else C.push("self-hosted runner")}const at=(x.product||"chant")+" check-job: "+x.job;if(P.length>0){for(const p of P)console.error(at+": "+p);console.error(at+": this job does not run where the spec set it to run, so it stops before any credential is taken or code checked out");process.exit(9)}console.log(at+": "+(C.length?C.join(", "):"nothing to check")+(S.length?"; not checked: "+S.join(", "):""))}).catch((e)=>fail(e&&e.message?e.message:String(e)));'')'
       - uses: https://code.forgejo.org/actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
@@ -97,6 +109,10 @@ jobs:
       - wave-2-prod-decide
     container: node:22
     steps:
+      - name: Check the job runs where the spec set it to run
+        env:
+          CHANT_JOB_GUARD: '{"forge":"forgejo","job":"job group eu of wave 2 (prod) of migrations","branches":["main"]}'
+        run: '(cd / && node -e ''"use strict";const E=process.env,A="chant-check-job";const shown=(v)=>v===undefined||v===null||v===""?"none":v;const fail=(m)=>{console.error("check-job: "+m);process.exit(9)};let x;try{x=JSON.parse(E.CHANT_JOB_GUARD||"")}catch(e){fail("CHANT_JOB_GUARD is not JSON")}if(!x||!["github","gitlab","forgejo"].includes(x.forge)||!Array.isArray(x.branches))fail("CHANT_JOB_GUARD is not a guard spec");const tags=(r)=>{if(r===undefined)return undefined;const t=r.trim();if(t.startsWith("[")){try{const v=JSON.parse(t);if(Array.isArray(v))return v.map(String)}catch(e){}}return t===""?[]:t.split(",").map((s)=>s.trim()).filter((s)=>s!=="")};const claimsOf=(tok)=>{const p=tok.split(".")[1];if(!p)throw new Error("the forge\u0027s OIDC token is not a JWT");const c=JSON.parse(Buffer.from(p.replace(/-/g,"+").replace(/_/g,"/"),"base64").toString("utf-8"));if(!c||typeof c!=="object")throw new Error("the forge\u0027s OIDC token has no claims");return c};async function seenOf(){if(x.forge==="gitlab")return{forgeEnvironment:E.CI_ENVIRONMENT_NAME||null,ref:E.CI_COMMIT_REF_NAME,refProtected:E.CI_COMMIT_REF_PROTECTED,runnerTags:tags(E.CI_RUNNER_TAGS)};const s={ref:E.GITHUB_REF};let c;if(x.forge==="github"&&x.forgeEnvironment!==undefined){try{if(!E.ACTIONS_ID_TOKEN_REQUEST_URL||!E.ACTIONS_ID_TOKEN_REQUEST_TOKEN)throw new Error("the job may request no OIDC token (no ACTIONS_ID_TOKEN_REQUEST_URL); it needs the id-token: write permission");const r=await fetch(E.ACTIONS_ID_TOKEN_REQUEST_URL+"&audience="+encodeURIComponent(A),{headers:{authorization:"bearer "+E.ACTIONS_ID_TOKEN_REQUEST_TOKEN}});if(!r.ok)throw new Error("the OIDC token request answered "+r.status);const v=(await r.json()).value;if(typeof v!=="string")throw new Error("the OIDC token request answered no token");c=claimsOf(v);s.forgeEnvironment=typeof c.environment==="string"&&c.environment!==""?c.environment:null}catch(e){s.forgeEnvironmentError=e&&e.message?e.message:String(e)}}const run=c&&typeof c.runner_environment==="string"?c.runner_environment:E.RUNNER_ENVIRONMENT;if(run)s.runnerEnvironment=run;return s}seenOf().then((s)=>{const P=[],C=[],S=[];const fe=x.forgeEnvironment;if(x.forge==="forgejo")S.push("forge environment (Forgejo has none)");else if(fe!==undefined){if(s.forgeEnvironmentError!==undefined)P.push("forge environment: expected "+fe+", and it could not be read: "+s.forgeEnvironmentError);else if(s.forgeEnvironment!==fe)P.push("forge environment: expected "+fe+", found "+shown(s.forgeEnvironment));else C.push("forge environment "+fe)}const b=x.branches.filter((v)=>v!=="");if(b.length===0)P.push("ref: the job names no branch to run from");else if(x.forge==="gitlab"){if(!s.ref||!b.includes(s.ref))P.push("ref: expected "+b.join(" or ")+", found "+shown(s.ref));else C.push("ref "+s.ref);if(s.refProtected!=="true")P.push("ref: expected a protected ref (CI_COMMIT_REF_PROTECTED true), found "+shown(s.refProtected));else C.push("protected ref")}else{const refs=b.map((v)=>"refs/heads/"+v);if(!s.ref||!refs.includes(s.ref))P.push("ref: expected "+refs.join(" or ")+", found "+shown(s.ref));else C.push("ref "+s.ref)}if(x.forge==="gitlab"){const w=x.runnerTags||[];if(w.length>0){const h=s.runnerTags;const miss=w.filter((t)=>!(h||[]).includes(t));if(h===undefined)P.push("runner: expected tags "+w.join(", ")+", and the job has no CI_RUNNER_TAGS");else if(miss.length>0)P.push("runner: expected tags "+w.join(", ")+", found "+(h.length?h.join(", "):"none"));else C.push("runner tags "+w.join(", "))}}else if(x.selfHosted){if(s.runnerEnvironment===undefined)S.push("runner (the runner says nothing about itself: no RUNNER_ENVIRONMENT)");else if(s.runnerEnvironment!=="self-hosted")P.push("runner: expected self-hosted, found "+s.runnerEnvironment);else C.push("self-hosted runner")}const at=(x.product||"chant")+" check-job: "+x.job;if(P.length>0){for(const p of P)console.error(at+": "+p);console.error(at+": this job does not run where the spec set it to run, so it stops before any credential is taken or code checked out");process.exit(9)}console.log(at+": "+(C.length?C.join(", "):"nothing to check")+(S.length?"; not checked: "+S.join(", "):""))}).catch((e)=>fail(e&&e.message?e.message:String(e)));'')'
       - uses: https://code.forgejo.org/actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0

package/src/components/ci-jobs.ts

@@ -77,5 +77,6 @@ export function forgejoWorkflowDoc(doc: GithubOpPipelineDoc, dialect: ForgejoDia
     jobsDoc: forgejoize(withoutEnvironment(doc.jobsDoc), dialect),
     ...(doc.gatedNoticeDoc ? { gatedNoticeDoc: forgejoize(doc.gatedNoticeDoc, dialect) } : {}),
     ...(doc.reviewNoteDoc ? { reviewNoteDoc: forgejoize(doc.reviewNoteDoc, dialect) } : {}),
+    ...(doc.agentDoc ? { agentDoc: forgejoize(doc.agentDoc, dialect) } : {}),
   };
 }

package/src/components/control-pipeline.ts

@@ -0,0 +1,27 @@
+/**
+ * The control repo's own workflow (#4568) on Forgejo: github's document
+ * (`controlGithubDoc`) with the Forgejo dialect applied, the way
+ * ./generate-pipeline.ts reuses github's pipeline. Forgejo has no
+ * `repository_dispatch`, so a member's dispatch is a workflow dispatch of
+ * this file by name.
+ */
+
+import {
+  controlGithubDoc,
+  type ControlPipelineFile,
+  type ControlPipelineOptions,
+} from "@intentius/chant-lexicon-github/components/control-pipeline";
+import { emitWorkflowYAML } from "@intentius/chant-lexicon-github/components/ci-jobs";
+import type { ForgejoDialectOptions } from "../dialect";
+import { forgejoize } from "./ci-jobs";
+
+/** The control repo's workflow on Forgejo: `.forgejo/workflows/<product>-dependents.yml`. */
+export function generateControlPipeline(options: ControlPipelineOptions = {}, dialect: ForgejoDialectOptions = {}): ControlPipelineFile {
+  const { doc, path, notes } = controlGithubDoc("forgejo", options);
+  const content = emitWorkflowYAML({
+    ...doc,
+    on: forgejoize(doc.on, dialect),
+    jobsDoc: forgejoize(doc.jobsDoc, dialect),
+  });
+  return { path, content, notes };
+}

package/src/components/generate-op-pipeline.agent.test.ts

@@ -0,0 +1,46 @@
+/**
+ * The agent jobs on Forgejo (#4616): github's jobs in the Forgejo dialect,
+ * with the commenter's access asked of the forge, and a runner a label.
+ */
+
+import { describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { ScheduledOpSpec } from "@intentius/chant/lexicon";
+import { generateForgejoOpPipeline } from "./generate-op-pipeline";
+
+const doc = (spec: ScheduledOpSpec) => parseYAML(generateForgejoOpPipeline([spec]).files[0]!.yaml) as unknown as { jobs: Record<string, { if?: string; "runs-on"?: unknown; steps: Array<{ run?: string; env?: Record<string, string> }> }> };
+
+describe("the comment agent on Forgejo", () => {
+  const d = doc({ name: "chant-agent", runner: "agents", agent: { on: "comment", comment: "/chant agent" } });
+
+  test("answers a comment on a pull request with no author association to read", () => {
+    const agent = d.jobs["chant-agent"]!;
+    expect(agent.if).toContain("github.event.is_pull");
+    expect(agent.if).not.toContain("author_association");
+    expect(agent["runs-on"]).toBe("agents");
+  });
+
+  test("the push job hands the forge client its token", () => {
+    const land = d.jobs["chant-agent-push"]!.steps.at(-1)!;
+    expect(land.run).toContain("chant agent land --forge forgejo");
+    expect(land.env?.CHANT_FORGEJO_TOKEN).toBeDefined();
+  });
+
+  test("refuses a runner group, which only GitHub has", () => {
+    expect(() => doc({ name: "drift-app", trigger: { kind: "cron", schedule: "0 6 * * *" }, runner: { group: "infra" } })).toThrow(/runner group/);
+  });
+});
+
+// #4619: on Forgejo too, a member's drift Op hands its own output on, and the agent job takes it at the root.
+describe("the drift agent of a workspace member on Forgejo", () => {
+  const out = generateForgejoOpPipeline([{ name: "drift-app", trigger: { kind: "cron", schedule: "0 6 * * *" }, agent: { on: "drift" } }], { member: { name: "app", dir: "stacks/app" } });
+  const d = parseYAML(out.files[0]!.yaml) as unknown as { jobs: Record<string, { defaults?: { run?: { "working-directory"?: string } }; steps: Array<{ name?: string; run?: string }> }> };
+
+  test("the drift check runs in the member's directory, and the agent job reads what it handed on", () => {
+    expect(d.jobs["drift-app"]!.defaults?.run?.["working-directory"]).toBe("stacks/app");
+    const agent = d.jobs["drift-app-agent"]!;
+    expect(agent.defaults).toBeUndefined();
+    expect(agent.steps.find((s) => s.name === "Take the drift from the drift check")!.run).toContain(" .chant/agent <<");
+    expect(agent.steps.some((s) => s.run?.includes("chant agent prepare --forge forgejo --output .chant/agent"))).toBe(true);
+  });
+});

package/src/components/generate-op-pipeline.cloud.test.ts

@@ -0,0 +1,25 @@
+/** #4631: the Forgejo scheduled Op job trades for its cloud identities first, and an update on drift runs in its own job. */
+import { describe, expect, test } from "vitest";
+import type { ScheduledOpSpec } from "@intentius/chant/lexicon";
+import { generateForgejoOpPipeline } from "./generate-op-pipeline";
+
+const PREVIEW = { aws: { role: "arn:aws:iam::1:role/preview", region: "us-east-1", audience: "sts.amazonaws.com" } };
+const UPDATE = { aws: { role: "arn:aws:iam::1:role/update", region: "us-east-1", audience: "sts.amazonaws.com" } };
+
+describe("cloud identities on a Forgejo scheduled Op (#4631)", () => {
+  test("the trade, id-token: write on the job, and the update job", () => {
+    const spec: ScheduledOpSpec = { name: "drift-dev", trigger: { kind: "cron", schedule: "0 6 * * *" }, findingMode: "issue", cloud: PREVIEW, update: { command: "plywood up", cloud: UPDATE } };
+    const yaml = generateForgejoOpPipeline([spec]).files[0]!.yaml;
+    expect(yaml).toContain("Trade the job's OIDC token for its cloud identities");
+    expect(yaml).toContain("id-token: write");
+    expect(yaml).toContain("drift-dev-update:");
+    expect(yaml).toContain("needs.drift-dev.outputs.drift == 'true'");
+    expect(yaml).toContain("role/update");
+  });
+
+  test("an update with contents: write renders, and the refusal of contents: read holds (2026-10-28 ruling)", () => {
+    const spec: ScheduledOpSpec = { name: "drift-dev", trigger: { kind: "cron", schedule: "0 6 * * *" }, findingMode: "issue", cloud: PREVIEW, update: { command: "plywood up", cloud: UPDATE, permissions: { contents: "write" } } };
+    expect(generateForgejoOpPipeline([spec]).files[0]!.yaml).toContain("drift-dev-update:");
+    expect(() => generateForgejoOpPipeline([{ ...spec, update: { command: "plywood up", permissions: { contents: "read" } } }])).toThrow(/contents may only be raised to write/);
+  });
+});

package/src/components/generate-op-pipeline.ts

@@ -95,6 +95,7 @@ import type {
   OpPipelineResult,
   ScheduledOpSpec,
 } from "@intentius/chant/lexicon";
+import { assertRunnerLabels } from "@intentius/chant/ci-jobs";
 import type { ForgejoDialectOptions } from "../dialect";
 import { droppedEnvironmentHeader, forgejoWorkflowDoc } from "./ci-jobs";
 
@@ -116,7 +117,9 @@ export function generateForgejoOpPipeline(
   // `findingMode: "issue"` from #2332 to #2351. Neither is now: both post
   // through the Forgejo client — see the module doc above.
 
-  const { files, jobs } = buildGithubOpPipelineDocs(ops, options);
+  // #4616: a spec's runner is a label or a list of labels here.
+  for (const spec of ops) assertRunnerLabels(`Scheduled Op "${spec.name}"`, "runner", spec.runner, "Forgejo");
+  const { files, jobs } = buildGithubOpPipelineDocs(ops, options, "forgejo");
 
   return {
     // One file per spec, in spec order, which is what lets the header below

package/src/components/generate-op-waves-pipeline.approval.test.ts

@@ -0,0 +1,26 @@
+/** #4630: the Forgejo plans workflow posts the approval status with `--forge forgejo`. */
+import { describe, expect, test } from "vitest";
+import type { OpWavesSpec } from "@intentius/chant/op/op-waves";
+import { generateForgejoOpWavesPipeline } from "./generate-op-waves-pipeline";
+
+const spec: OpWavesSpec = {
+  name: "plywood-up",
+  op: "plywood-up",
+  plan: ["./bin/plan", "{target}", "{plan}"],
+  waves: [{ name: "prod", runs: [{ target: "app" }], approval: "pr-review" }],
+};
+
+describe("the approval status job on Forgejo (#4630)", () => {
+  test("runs on reviews and after the plans with --forge forgejo", () => {
+    const plans = generateForgejoOpWavesPipeline(spec, { specFile: "waves.json" }).files.find((f) => f.name === "plywood-up-plans.yml")!.yaml;
+    expect(plans).toContain("pull_request_review:");
+    expect(plans).toContain('run wave --spec waves.json --approval-status --pr "$PR_NUMBER" --head "$HEAD_SHA" --base "$BASE_SHA" --forge forgejo');
+  });
+
+  test("a pull-request wave gets the plans workflow too (2026-10-28 ruling)", () => {
+    const pullRequest: OpWavesSpec = { ...spec, waves: [{ name: "prod", runs: [{ target: "app" }], approval: "pull-request" }], approvals: { pullRequest: { gate: "up" } } };
+    const plans = generateForgejoOpWavesPipeline(pullRequest, { specFile: "waves.json" }).files.find((f) => f.name === "plywood-up-plans.yml")!.yaml;
+    expect(plans).toContain("run wave --spec waves.json --record-plans");
+    expect(plans).toContain("--approval-status --pr");
+  });
+});

package/src/components/generate-op-waves-pipeline.control.test.ts

@@ -0,0 +1,38 @@
+/**
+ * An Op waves spec's `control` on Forgejo (#4617): github's control job
+ * under the dialect, dispatching the control repo's dependents workflow by
+ * name with the outcome as an input. Written for the ci-products session;
+ * run at epic-ready.
+ */
+
+import { describe, expect, test } from "vitest";
+import type { OpWavesSpec } from "@intentius/chant/op/op-waves";
+import { generateForgejoOpWavesPipeline } from "./generate-op-waves-pipeline";
+
+const spec: OpWavesSpec = {
+  name: "stacks",
+  op: "pulumi-up",
+  plan: ["./bin/plan", "{target}", "{plan}"],
+  waves: [{ name: "all", runs: [{ target: "dev" }, { target: "prod" }] }],
+  control: { repo: "forgejo.example.com/acme/control", op: "deploy", member: "network", ref: "trunk" },
+};
+
+const options = { specFile: "waves.json", bin: "npx --no-install plywood", words: { product: "plywood" } };
+
+describe("the control dispatch after the last wave on Forgejo (#4617)", () => {
+  test("a workflow dispatch of the control repo's dependents file, the outcome among its inputs", () => {
+    const yaml = generateForgejoOpWavesPipeline(spec, options).files[0]!.yaml;
+    expect(yaml).toMatch(/control-dispatch:[\s\S]*needs:\n\s+- wave-1-all\n\s+if: '!cancelled\(\)'/);
+    expect(yaml).toContain("https://forgejo.example.com/api/v1/repos/acme/control/actions/workflows/plywood-dependents.yml/dispatches");
+    expect(yaml).toContain(`{"ref":"trunk","inputs":{"member":"'"$member"'","op":"'"$op"'","sha":"'"$sha"'","outcome":"'"$outcome"'"}}`);
+    expect(yaml).toContain("Authorization: token %s");
+    expect(yaml).toContain("CHANT_CONTROL_TOKEN: '${{ secrets.CHANT_CONTROL_TOKEN }}'");
+    expect(yaml).toContain("npx --no-install plywood run wave --spec waves.json --waves-outcome");
+  });
+
+  test("the dialect drops permissions and rewrites the download action", () => {
+    const yaml = generateForgejoOpWavesPipeline(spec, options).files[0]!.yaml;
+    expect(yaml).not.toContain("permissions:");
+    expect(yaml).toContain("name: Download the waves' outcomes");
+  });
+});

package/src/components/generate-op-waves-pipeline.guard.test.ts

@@ -0,0 +1,31 @@
+/**
+ * The apply-job guard in Forgejo op-wave jobs (#4624): the GitHub step with
+ * the forge set to Forgejo, which checks the ref and runner and no
+ * environment. Written for the ci-products post-merge pass.
+ */
+
+import { describe, expect, test } from "vitest";
+import type { OpWavesSpec } from "@intentius/chant/op/op-waves";
+import { JOB_GUARD_ENV } from "@intentius/chant/ci-job-guard";
+import { generateForgejoOpWavesPipeline } from "./generate-op-waves-pipeline";
+
+const spec: OpWavesSpec = {
+  name: "deploy",
+  op: "pulumi-up",
+  plan: ["./bin/plan", "{target}", "{plan}"],
+  runner: ["self-hosted", "docker"],
+  waves: [{ name: "prod", runs: [{ target: "prod" }], environment: { name: "production" }, idTokens: { CLOUD_TOKEN: "aud" } }],
+};
+
+describe("the apply-job guard on Forgejo (#4624)", () => {
+  test("the first step of the wave job, with the forge set to Forgejo and no environment", () => {
+    const yaml = generateForgejoOpWavesPipeline(spec, { specFile: "waves.json" }).files[0]!.yaml;
+    const steps = yaml.slice(yaml.indexOf("steps:"));
+    expect(steps.indexOf("Check the job runs where the spec set it to run")).toBeLessThan(steps.indexOf("checkout"));
+    expect(yaml).toContain(JOB_GUARD_ENV);
+    const json = /CHANT_JOB_GUARD: '(\{.*?\})'/.exec(yaml)?.[1] ?? /CHANT_JOB_GUARD: "(.*?)"\n/.exec(yaml)?.[1]?.replace(/\\"/g, '"');
+    expect(json).toBeDefined();
+    const guard = JSON.parse(json!) as Record<string, unknown>;
+    expect(guard).toEqual({ forge: "forgejo", job: "wave 1 (prod) of deploy", branches: ["main"], selfHosted: true });
+  });
+});

package/src/components/generate-op-waves-pipeline.test.ts

@@ -115,8 +115,26 @@ describe("an Op wave's jobs by cloud identity (#4332)", () => {
     expect(Object.keys(jobs)).toEqual(["wave-1-prod-decide", "wave-1-prod-a", "wave-1-prod-default"]);
     for (const job of Object.values(jobs)) {
       expect(job.permissions).toEqual({ "id-token": "write" });
-      expect(job.steps[0]!.env![TRADE_SPEC_ENV]).toBeDefined();
-      expect(job.steps[1]!.uses).toContain("checkout");
+      // #4624: the apply-job guard comes first, then the trade, then the checkout.
+      expect(job.steps[1]!.env![TRADE_SPEC_ENV]).toBeDefined();
+      expect(job.steps[2]!.uses).toContain("checkout");
     }
   });
+
+  test("words.bin is the command in every job line: the waves, resume and the plans job (#4607)", () => {
+    const bin = "npx --no-install plywood";
+    const withBin = { ...spec, resume: { schedule: "*/10 * * * *" }, waves: spec.waves.map((w, i) => (i === spec.waves.length - 1 ? { ...w, approval: "pr-review" as const } : w)) };
+    const { files, jobs } = generateForgejoOpWavesPipeline(withBin, { specFile: "waves.json", bin });
+    expect(jobs.every((j) => j.command.slice(0, 3).join(" ") === bin)).toBe(true);
+    const yaml = files.map((f) => f.yaml).join("\n");
+    expect(yaml).toContain("run: npx --no-install plywood run wave --spec waves.json --wave 1");
+    expect(yaml).toContain("npx --no-install plywood run resume --op migrations");
+    expect(yaml).toContain("npx --no-install plywood run wave --spec waves.json --record-plans");
+    expect(yaml).not.toMatch(/(^|\s)chant run (wave|resume)/m);
+  });
+
+  test("no bin keeps chant (#4607)", () => {
+    const { jobs } = generateForgejoOpWavesPipeline(spec, { specFile: "waves.json" });
+    expect(jobs.every((j) => j.command[0] === "chant")).toBe(true);
+  });
 });

package/src/components/generate-op-waves-pipeline.ts

@@ -12,8 +12,8 @@
  * so it dispatches the waves workflow again on its branch, with the
  * `CHANT_FORGE_TOKEN` secret (a token with the `write:repository` scope).
  *
- * A `pr-review` wave (#3684) gets `<name>-plans.yml` on pull requests, as on
- * GitHub. Forgejo's job token reads reviews with no permission to ask for.
+ * A `pr-review` wave (#3684), or a `pull-request` wave (#4630), gets
+ * `<name>-plans.yml` on pull requests, as on GitHub. Forgejo's job token reads reviews with no permission to ask for.
  *
  * `runner` and a wave's `jobs` (#3914) render as on GitHub, with two limits:
  * a runner is a label or a list of labels (a GitHub runner group is a spec
@@ -21,6 +21,10 @@
  * none to put in front of it. A job with id tokens keeps `permissions:
  * id-token: write`, the one scope the dialect leaves, and reads each audience
  * from `<NAME>_AUDIENCE` when it requests its token.
+ *
+ * The apply-job guard (#4624) starts each wave job as on GitHub, with the
+ * forge set to Forgejo: it checks the ref and, for a `self-hosted` label,
+ * the runner, and no forge environment, since Forgejo has none.
  */
 
 import { buildGithubOpWavesDoc } from "@intentius/chant-lexicon-github/components/generate-op-waves-pipeline";
@@ -38,7 +42,7 @@ export function generateForgejoOpWavesPipeline(
   dialectOptions: ForgejoDialectOptions = {},
 ): OpWavesPipelineResult {
   assertForgejoWaves(spec);
-  const { doc, jobs, resumeDoc, plansDoc } = buildGithubOpWavesDoc(spec, options);
+  const { doc, jobs, resumeDoc, plansDoc } = buildGithubOpWavesDoc(spec, options, { forge: "forgejo" });
   const dropped = spec.waves.filter((w) => w.environment).map((w) => `${w.name} -> ${w.environment!.name}`);
   const header = dropped.length > 0 ? droppedWaveEnvironmentsHeader(dropped) : undefined;
   const files = [{ name: `${spec.name}.yml`, yaml: emitOpPipelineYAML(forgejoWorkflowDoc(doc, dialectOptions, header)) }];

package/src/components/generate-pr-pipeline.comment-locks.test.ts

@@ -0,0 +1,25 @@
+/** `/<product> lock` and `/<product> unlock` on Forgejo (#4588): the GitHub generator's comment jobs, reading Forgejo's `is_pull`, with no author check. */
+
+import { describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { generateForgejoPipeline } from "./generate-pipeline";
+
+const ESTATE: DriverComponent[] = [
+  { name: "net", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "net" }] }] },
+];
+
+const WORDS = { product: "plywood", commands: { lock: "lock" as const, unlock: "unlock" as const } };
+
+type Doc = { jobs: Record<string, { if?: string; steps: Array<{ run?: string }> }> };
+
+describe("the Forgejo workflow's lock and unlock comments", () => {
+  const doc = parseYAML(generateForgejoPipeline(ESTATE, { env: "prod", prLoop: { locks: "plan", words: WORDS } }).yaml) as Doc;
+
+  test("each comment job reads is_pull and runs on forgejo", () => {
+    expect(doc.jobs["comment-lock"]!.if).toContain("github.event.is_pull");
+    expect(doc.jobs["comment-lock"]!.if).not.toContain("author_association");
+    expect(doc.jobs["comment-lock"]!.steps.some((s) => s.run === 'chant lock --keep --pr "$PR_NUMBER" --forge forgejo')).toBe(true);
+    expect(doc.jobs["comment-unlock"]!.steps.some((s) => s.run === 'chant unlock --pr "$PR_NUMBER"')).toBe(true);
+  });
+});

package/src/components/generate-pr-pipeline.comment-preview.test.ts

@@ -0,0 +1,31 @@
+/** The preview comment on Forgejo (#4620): the GitHub generator's jobs, reading Forgejo's `is_pull`, with no author check. */
+
+import { describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { generateForgejoPipeline } from "./generate-pipeline";
+
+const ESTATE: DriverComponent[] = [
+  { name: "net", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "net" }] }] },
+];
+
+const WORDS = { product: "plywood", stages: { plan: "preview", apply: "up" }, commands: { preview: "plan" as const } };
+
+type Doc = { jobs: Record<string, { if?: string; permissions?: Record<string, string>; steps: Array<{ run?: string }> }> };
+
+describe("the Forgejo workflow's preview comment", () => {
+  const doc = parseYAML(generateForgejoPipeline(ESTATE, { env: "prod", prLoop: { previewComment: true, words: WORDS } }).yaml) as Doc;
+
+  test("the preview job reads is_pull, drops the tokens before the change's code runs, and the note job posts on forgejo", () => {
+    const preview = doc.jobs["comment-preview"]!;
+    expect(preview.if).toContain("github.event.is_pull");
+    expect(preview.if).not.toContain("author_association");
+    // The Forgejo runner ignores `permissions`, so the dialect drops it (bar id-token), as for every job.
+    expect(preview.permissions).toBeUndefined();
+    const drop = preview.steps.findIndex((s) => s.run?.includes("-u CHANT_FORGE_TOKEN") ?? false);
+    const plan = preview.steps.findIndex((s) => s.run?.includes("pr-plan") ?? false);
+    expect(drop).toBeGreaterThan(0);
+    expect(plan).toBeGreaterThan(drop);
+    expect(doc.jobs["comment-preview-note"]!.steps.at(-1)!.run).toBe('chant components pr-post --pr "$PR_NUMBER" --head "$HEAD_SHA" --env prod --output .chant/pr --forge forgejo --result "$PLAN_RESULT"');
+  });
+});

package/src/components/generate-pr-pipeline.comment-targets.test.ts

@@ -0,0 +1,18 @@
+/**
+ * The preview comment's --target on Forgejo (#4626): the GitHub generator's
+ * preview step, with the comment body in CHANT_PREVIEW_COMMENT. Written for
+ * the ci-products post-merge pass.
+ */
+import { expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { generateForgejoPipeline } from "./generate-pipeline";
+
+const ESTATE: DriverComponent[] = [{ name: "net", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "net" }] }] }];
+const WORDS = { product: "plywood", stages: { plan: "preview", apply: "up" }, commands: { preview: "plan" as const } };
+
+test("the preview step reads the comment from a variable (#4626)", () => {
+  const doc = parseYAML(generateForgejoPipeline(ESTATE, { env: "prod", prLoop: { previewComment: true, words: WORDS } }).yaml) as { jobs: Record<string, { steps: Array<{ run?: string; env?: Record<string, string> }> }> };
+  const step = doc.jobs["comment-preview"]!.steps.find((s) => s.run?.includes("--comment-targets"))!;
+  expect(step.env!.CHANT_PREVIEW_COMMENT).toBe("${{ github.event.comment.body }}");
+});

package/src/components/generate-pr-pipeline.control.test.ts

@@ -0,0 +1,30 @@
+/**
+ * #4619: with a control repo, the Forgejo pull-request workflow's plan-note
+ * job fetches the control repo's chant/lifecycle, read-only, and sets
+ * CHANT_CONTROL_DIR before it posts, through the Forgejo dialect. Generated
+ * YAML only.
+ */
+
+import { describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { resolveControlTarget } from "@intentius/chant/control/dispatch";
+import { generateForgejoPipeline } from "./generate-pipeline";
+
+const root = (name: string, dependsOn: string[] = []): DriverComponent => ({ name, dependsOn, deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: name }] }] });
+const ESTATE: DriverComponent[] = [root("net"), root("app", ["net"])];
+const control = { target: resolveControlTarget({ repo: "forgejo.example.com/acme/control", op: "deploy", readTokenSecret: "PLYWOOD_CONTROL_READ" }, "network") };
+
+describe("the Forgejo plan-note job's read of the control repo (#4619)", () => {
+  test("fetches the control repo's chant/lifecycle with the read secret before it posts", () => {
+    const { yaml } = generateForgejoPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true, control, words: { product: "plywood" } } });
+    const doc = parseYAML(yaml) as { jobs: Record<string, { steps: Array<{ run?: string; env?: Record<string, string> }> }> };
+    const steps = doc.jobs["plan-note"]!.steps;
+    const read = steps.findIndex((s) => s.run?.includes("refs/heads/chant/lifecycle"));
+    expect(read).toBeGreaterThan(-1);
+    expect(steps[read + 1]!.run).toContain("components pr-post");
+    expect(steps[read]!.env?.CHANT_CONTROL_READ_TOKEN).toBe("${{ secrets.PLYWOOD_CONTROL_READ || github.token }}");
+    expect(steps[read]!.run).toContain("'https://forgejo.example.com/acme/control.git'");
+    expect(steps[read]!.run).toContain(">>\"$GITHUB_ENV\"");
+  });
+});

package/src/components/generate-pr-pipeline.runners.test.ts

@@ -0,0 +1,24 @@
+/**
+ * The pull request loop's runners and passed secrets on Forgejo (#4625):
+ * the GitHub generator's, through the dialect. Written for the ci-products
+ * post-merge pass.
+ */
+
+import { describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { generateForgejoPipeline } from "./generate-pipeline";
+
+const ESTATE: DriverComponent[] = [{ name: "net", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "net" }] }] }];
+
+type Doc = { jobs: Record<string, { "runs-on": unknown; steps: Array<{ name?: string; env?: Record<string, string> }> }> };
+
+describe("the Forgejo pull request loop's runners and secrets (#4625)", () => {
+  test("the plan runs on its stage's runner with the passed secret", () => {
+    const doc = parseYAML(generateForgejoPipeline(ESTATE, { env: "prod", prLoop: { runners: { plan: "big", default: "small" }, secrets: { DB_PASSWORD: "PROD_DB" } } }).yaml) as Doc;
+    expect(doc.jobs.plan!["runs-on"]).toBe("big");
+    expect(doc.jobs["plan-note"]!["runs-on"]).toBe("small");
+    const step = doc.jobs.plan!.steps.find((s) => s.name === "Plan the members this pull request reaches")!;
+    expect(step.env).toMatchObject({ DB_PASSWORD: "${{ secrets.PROD_DB }}" });
+  });
+});

package/src/components/generate-pr-pipeline.stale-notes.test.ts

@@ -0,0 +1,12 @@
+/** Stale marking on Forgejo (#4628): the GitHub generator's stale-notes job, posting on forgejo. Written for the ci-products post-merge pass. */
+import { expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { generateForgejoPipeline } from "./generate-pipeline";
+
+const ESTATE: DriverComponent[] = [{ name: "net", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "net" }] }] }];
+
+test("a stale-notes job runs pr-post --stale on forgejo (#4628)", () => {
+  const doc = parseYAML(generateForgejoPipeline(ESTATE, { env: "prod", prLoop: { staleNotes: true } }).yaml) as { jobs: Record<string, { steps: Array<{ run?: string }> }> };
+  expect(doc.jobs["stale-notes"]!.steps.at(-1)!.run).toBe('chant components pr-post --stale --tip "$TIP_SHA" --env prod --forge forgejo');
+});