@intentius/chant-lexicon-github 0.59.0 → 0.61.0

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

@@ -46,8 +46,19 @@
  * reason) and never touching one it does; {@link mergePermissions} refuses a
  * blanket grant, an overlap with the mode's own set, an unknown scope name,
  * and pull-request write on a trigger that has no pull request.
+ *
+ * A third widens it the other way (#2257): a spec's `environment` emits
+ * `environment:` on the Op's own job, which is how a GitHub environment's
+ * protection rules — required reviewers above all — come to hold a generated
+ * apply. That is a second gate beside chant's own, not a replacement for it:
+ * the reviewer stops the job before any step runs, chant's gate ledger
+ * (#2119) stops the apply inside a run that already started, and the two
+ * compose in either combination. It costs {@link permissionsFor} nothing —
+ * environment protection is repository configuration, not a token scope — and
+ * {@link assertEnvironment} refuses only what would emit as configured and
+ * bind nothing.
  */
-import type { ComponentPipelineOptions as GenerateGithubOpOptions, OpPipelineJob, OpPipelineResult as GenerateGithubOpResult, OpSetupStep, OpTrigger, ScheduledOpSpec } from "@intentius/chant/lexicon";
+import type { ComponentPipelineOptions as GenerateGithubOpOptions, OpEnvironment, OpPipelineJob, OpPipelineResult as GenerateGithubOpResult, OpSetupStep, OpTrigger, ScheduledOpSpec } from "@intentius/chant/lexicon";
 export type { GenerateGithubOpOptions, GenerateGithubOpResult };
 /**
  * The structured pipeline document behind one generated file, before YAML
@@ -57,6 +68,15 @@ export type { GenerateGithubOpOptions, GenerateGithubOpResult };
  * `./generate-pipeline.ts`'s `GithubPipelineDoc` split.
  */
 export interface GithubOpPipelineDoc {
+    /**
+     * Comment lines emitted above the document, `#` prefix included, when a
+     * dialect has something to say about what it could not carry across
+     * (#2257). Empty on github, which drops nothing; the forgejo dialect uses
+     * it to name the `environment:` its runner has no concept of, so the fact
+     * that a reviewer gate did not survive is readable in the generated file
+     * rather than only in a build warning.
+     */
+    header?: string[];
     /**
      * The `on:` trigger mapping, per {@link ScheduledOpSpec}'s trigger kind
      * (#2084): `{ schedule, workflow_dispatch }` for cron, `{ pull_request }`
@@ -80,8 +100,10 @@ export interface GithubOpPipelineDoc {
      * Kept out of {@link jobsDoc} so a dialect that cannot run it drops it by
      * simply not copying it: the job shells to `gh` against the GitHub API and
      * needs `gh` on the runner, which is the same reason the `comment` finding
-     * mode is refused on forgejo and gitlab (#2231). {@link emitOpPipelineYAML}
-     * merges it into `jobs:` for the forges that can.
+     * mode is refused on forgejo (#2231). {@link emitOpPipelineYAML} merges it
+     * into `jobs:` for the forges that can. GitLab reaches the same outcome
+     * without this job at all: its push job writes the pending block to an
+     * artifact instead (#2256).
      */
     gatedNoticeDoc?: Record<string, unknown>;
 }
@@ -102,6 +124,18 @@ export interface GithubOpPipelineFile {
  * cannot know a local path resolves there.
  */
 export declare function assertSetupSteps(name: string, setup: OpSetupStep[]): void;
+/**
+ * Validate a spec's `environment` (#2257). GitHub creates an environment it
+ * has never seen on first use rather than failing the run, and an environment
+ * created that way carries no protection rules at all — so a job can name one
+ * and read as gated while being gated by nothing. Neither this generator nor
+ * GitHub can tell those apart at build time (the environment and its
+ * reviewers are repository configuration, not workflow content), which is why
+ * what is refused here is only the shape that could never bind: a name that
+ * is blank, and a `url` that is neither absolute nor an expression the forge
+ * resolves. The rest is the README's job to say out loud.
+ */
+export declare function assertEnvironment(name: string, environment: OpEnvironment): void;
 /**
  * Merge a spec's additive `permissions` over the finding-mode's own set
  * (#2242), refusing by name anything that is not strictly additive:

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAIH,OAAO,KAAK,EACV,wBAAwB,IAAI,uBAAuB,EAEnD,aAAa,EACb,gBAAgB,IAAI,sBAAsB,EAC1C,WAAW,EACX,SAAS,EACT,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAElC,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,CAAC;AAEhE;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5B,2DAA2D;IAC3D,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAED,qFAAqF;AACrF,MAAM,WAAW,oBAAoB;IACnC,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,mBAAmB,CAAC;CAC1B;AAsQD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,IAAI,CA8BzE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,EACtC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,EAC1C,OAAO,EAAE,SAAS,GACjB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAqClC;AAiBD;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,GACpC;IAAE,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAAC,IAAI,EAAE,aAAa,EAAE,CAAA;CAAE,CAiF1D;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,mBAAmB,GAAG,MAAM,CAWnE;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,GACpC,sBAAsB,CAMxB"}
+{"version":3,"file":"generate-op-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAIH,OAAO,KAAK,EACV,wBAAwB,IAAI,uBAAuB,EACnD,aAAa,EAEb,aAAa,EACb,gBAAgB,IAAI,sBAAsB,EAC1C,WAAW,EACX,SAAS,EACT,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAElC,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,CAAC;AAEhE;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;;OAIG;IACH,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5B,2DAA2D;IAC3D,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC;;;;;;;;;OASG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAED,qFAAqF;AACrF,MAAM,WAAW,oBAAoB;IACnC,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,mBAAmB,CAAC;CAC1B;AAsQD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,IAAI,CA8BzE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,aAAa,GAAG,IAAI,CAwBhF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,EACtC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,EAC1C,OAAO,EAAE,SAAS,GACjB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAqClC;AA6BD;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,GACpC;IAAE,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAAC,IAAI,EAAE,aAAa,EAAE,CAAA;CAAE,CAuF1D;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,mBAAmB,GAAG,MAAM,CAenE;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,GACpC,sBAAsB,CAMxB"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "3015db1776d8467a6769b316b4ffde3bbd225d53df528e97605b4b1645be3f27",
+    "manifest.json": "81759e8725dbe9f79f6747195efe17ce7e0504182857c99a317784b02c7ef629",
     "meta.json": "dc3977afc2b6ddc4904de906d1b1e448b786b2aced9d82f8eade2ff915203344",
     "types/index.d.ts": "f207946d7ab52f712d0c09995366440a6bba8b39358057b0da38ff9c0acca429",
     "rules/deprecated-action-version.ts": "d41e6e532ab7f623af1bee4ac5279fcb2baada7defa1c5d022a5bc71983e8797",
@@ -77,5 +77,5 @@
     "skills/chant-github-patterns.md": "bb3abef289a8fdfcf07d6bb2d7289dcb2f38bc0cb0321ea320b78b45a6f548c0",
     "skills/chant-github-security.md": "aab111cb0871cad30281ce48d7da23663689619351029219e2be019a1a61e394"
   },
-  "composite": "17318d4ba3cbdc98681abd0d398a4e5ea0c596397464c6622c53e6f2289669e4"
+  "composite": "b47a71d4987ee8534216ed299add82e196f2ba21026e79bf6490473bb8df525c"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "github",
-  "version": "0.59.0",
+  "version": "0.61.0",
   "chantVersion": ">=0.1.0",
   "namespace": "GitHub",
   "intrinsics": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-github",
-  "version": "0.59.0",
+  "version": "0.61.0",
   "description": "GitHub Actions lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -61,7 +61,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.59.0",
+    "@intentius/chant": "^0.61.0",
     "typescript": "^5.9.3"
   }
 }

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

@@ -27,6 +27,7 @@ interface ParsedStep {
 interface ParsedJob {
   "runs-on"?: string;
   container?: string;
+  environment?: Record<string, string>;
   needs?: string;
   if?: string;
   permissions?: Record<string, string>;
@@ -515,3 +516,129 @@ describe("generateGithubOpPipeline: the gated apply on push (#2243)", () => {
     expect(step?.run).toContain("set -o pipefail");
   });
 });
+
+/**
+ * chant #2257 — the second gate. A GitHub environment carries its own
+ * protection rules (required reviewers above all), and until this existed no
+ * generated job named one, so a `production` environment declared in a
+ * repository bound nothing chant generated. What is asserted here is the key
+ * on the right job, the key's absence everywhere else, and that adding it
+ * changes nothing else in the document.
+ */
+describe("generateGithubOpPipeline: a deployment environment on the Op's job (#2257)", () => {
+  const APPLY: ScheduledOpSpec = { name: "app-apply", trigger: { kind: "push", branches: ["main"] } };
+  const GATED: ScheduledOpSpec = { ...APPLY, environment: { name: "production" } };
+
+  /**
+   * The exact document a spec with no `environment` emitted before the option
+   * existed, produced by the generator at the commit this change branched
+   * from. The claim the option makes is that it is additive; this is what
+   * makes that claim falsifiable rather than a sentence in a PR body.
+   */
+  const AUDIT_YAML_BEFORE_2257 =
+    [
+      "on:",
+      "  schedule:",
+      "    - cron: '0 6 * * *'",
+      "  workflow_dispatch: {}",
+      "",
+      "concurrency:",
+      "  group: actions-audit",
+      "  cancel-in-progress: false",
+      "",
+      "permissions:",
+      "  contents: read",
+      "  issues: write",
+      "",
+      "jobs:",
+      "  actions-audit:",
+      "    runs-on: ubuntu-latest",
+      "    container: node:22-slim",
+      "    steps:",
+      "      - uses: actions/checkout@v4",
+      "      - run: chant run actions-audit",
+      "        env:",
+      "          GITHUB_TOKEN: '${{ github.token }}'",
+      "          GH_TOKEN: '${{ github.token }}'",
+    ].join("\n") + "\n";
+
+  test("a spec with no environment emits the bytes it emitted before the option existed", () => {
+    const yaml = generateGithubOpPipeline([
+      { name: "actions-audit", schedule: "0 6 * * *", findingMode: "issue" },
+    ]).files[0].yaml;
+    expect(yaml).toBe(AUDIT_YAML_BEFORE_2257);
+  });
+
+  test("emits environment: on the Op's job, as a mapping rather than the string shorthand", () => {
+    const job = parseFile(generateGithubOpPipeline([GATED]).files[0].yaml).jobs!["app-apply"];
+    expect(job.environment).toEqual({ name: "production" });
+  });
+
+  test("carries the url when the spec sets one", () => {
+    const spec: ScheduledOpSpec = {
+      ...APPLY,
+      environment: { name: "production", url: "https://app.example.com" },
+    };
+    const job = parseFile(generateGithubOpPipeline([spec]).files[0].yaml).jobs!["app-apply"];
+    expect(job.environment).toEqual({
+      name: "production",
+      url: "https://app.example.com",
+    });
+  });
+
+  test("adding the environment changes exactly the environment block and nothing else", () => {
+    const before = generateGithubOpPipeline([APPLY]).files[0].yaml;
+    const after = generateGithubOpPipeline([GATED]).files[0].yaml;
+    expect(after).toContain("    environment:\n      name: production\n");
+    expect(after.replace("    environment:\n      name: production\n", "")).toBe(before);
+  });
+
+  test("the gate-notice job is not held behind the same reviewer", () => {
+    // It exists to say a chant gate is pending. Behind the environment it
+    // would only be readable after somebody had already released the job it
+    // is reporting on, which is after the message stops being useful.
+    const notice = parseFile(generateGithubOpPipeline([GATED]).files[0].yaml).jobs![
+      "app-apply-gate-notice"
+    ];
+    expect(notice.environment).toBeUndefined();
+  });
+
+  test("costs no token scope: environment protection is repository configuration", () => {
+    // `permissionsFor` gains nothing from the option — the reviewer lives on
+    // the environment object, not on GITHUB_TOKEN — so the workflow-level set
+    // is identical with and without it.
+    const withEnv = parseFile(generateGithubOpPipeline([GATED]).files[0].yaml);
+    const withoutEnv = parseFile(generateGithubOpPipeline([APPLY]).files[0].yaml);
+    expect(withEnv.permissions).toEqual(withoutEnv.permissions);
+    expect(withEnv.permissions).toEqual({ contents: "read" });
+  });
+
+  test("applies to any trigger, so a pull_request plan can name a review environment too", () => {
+    const spec: ScheduledOpSpec = {
+      name: "app-plan",
+      trigger: { kind: "pull_request", branches: ["main"] },
+      findingMode: "comment",
+      environment: { name: "review", url: "${{ steps.deploy.outputs.url }}" },
+    };
+    const job = parseFile(generateGithubOpPipeline([spec]).files[0].yaml).jobs!["app-plan"];
+    expect(job.environment?.name).toBe("review");
+  });
+
+  test("refuses a blank environment name, which resolves to nothing", () => {
+    expect(() =>
+      generateGithubOpPipeline([{ ...APPLY, environment: { name: "   " } }]),
+    ).toThrow(/environment has an empty `name`/);
+  });
+
+  test("refuses a url that is neither absolute nor an expression, which renders as a dead link", () => {
+    expect(() =>
+      generateGithubOpPipeline([{ ...APPLY, environment: { name: "production", url: "/deploys" } }]),
+    ).toThrow(/neither an absolute http\(s\) URL nor a/);
+  });
+
+  test("refuses an empty url rather than emitting one", () => {
+    expect(() =>
+      generateGithubOpPipeline([{ ...APPLY, environment: { name: "production", url: "" } }]),
+    ).toThrow(/has an empty `url`/);
+  });
+});

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

@@ -46,12 +46,24 @@
  * reason) and never touching one it does; {@link mergePermissions} refuses a
  * blanket grant, an overlap with the mode's own set, an unknown scope name,
  * and pull-request write on a trigger that has no pull request.
+ *
+ * A third widens it the other way (#2257): a spec's `environment` emits
+ * `environment:` on the Op's own job, which is how a GitHub environment's
+ * protection rules — required reviewers above all — come to hold a generated
+ * apply. That is a second gate beside chant's own, not a replacement for it:
+ * the reviewer stops the job before any step runs, chant's gate ledger
+ * (#2119) stops the apply inside a run that already started, and the two
+ * compose in either combination. It costs {@link permissionsFor} nothing —
+ * environment protection is repository configuration, not a token scope — and
+ * {@link assertEnvironment} refuses only what would emit as configured and
+ * bind nothing.
  */
 
 import { emitYAML } from "@intentius/chant/yaml";
 import { resolveOpTrigger } from "@intentius/chant/lexicon";
 import type {
   ComponentPipelineOptions as GenerateGithubOpOptions,
+  OpEnvironment,
   OpFindingMode,
   OpPipelineJob,
   OpPipelineResult as GenerateGithubOpResult,
@@ -70,6 +82,15 @@ export type { GenerateGithubOpOptions, GenerateGithubOpResult };
  * `./generate-pipeline.ts`'s `GithubPipelineDoc` split.
  */
 export interface GithubOpPipelineDoc {
+  /**
+   * Comment lines emitted above the document, `#` prefix included, when a
+   * dialect has something to say about what it could not carry across
+   * (#2257). Empty on github, which drops nothing; the forgejo dialect uses
+   * it to name the `environment:` its runner has no concept of, so the fact
+   * that a reviewer gate did not survive is readable in the generated file
+   * rather than only in a build warning.
+   */
+  header?: string[];
   /**
    * The `on:` trigger mapping, per {@link ScheduledOpSpec}'s trigger kind
    * (#2084): `{ schedule, workflow_dispatch }` for cron, `{ pull_request }`
@@ -93,8 +114,10 @@ export interface GithubOpPipelineDoc {
    * Kept out of {@link jobsDoc} so a dialect that cannot run it drops it by
    * simply not copying it: the job shells to `gh` against the GitHub API and
    * needs `gh` on the runner, which is the same reason the `comment` finding
-   * mode is refused on forgejo and gitlab (#2231). {@link emitOpPipelineYAML}
-   * merges it into `jobs:` for the forges that can.
+   * mode is refused on forgejo (#2231). {@link emitOpPipelineYAML} merges it
+   * into `jobs:` for the forges that can. GitLab reaches the same outcome
+   * without this job at all: its push job writes the pending block to an
+   * artifact instead (#2256).
    */
   gatedNoticeDoc?: Record<string, unknown>;
 }
@@ -408,6 +431,43 @@ export function assertSetupSteps(name: string, setup: OpSetupStep[]): void {
   });
 }
 
+/**
+ * Validate a spec's `environment` (#2257). GitHub creates an environment it
+ * has never seen on first use rather than failing the run, and an environment
+ * created that way carries no protection rules at all — so a job can name one
+ * and read as gated while being gated by nothing. Neither this generator nor
+ * GitHub can tell those apart at build time (the environment and its
+ * reviewers are repository configuration, not workflow content), which is why
+ * what is refused here is only the shape that could never bind: a name that
+ * is blank, and a `url` that is neither absolute nor an expression the forge
+ * resolves. The rest is the README's job to say out loud.
+ */
+export function assertEnvironment(name: string, environment: OpEnvironment): void {
+  const where = `Scheduled Op "${name}" environment`;
+  if (environment.name.trim() === "") {
+    throw new Error(
+      `${where} has an empty \`name\`. An environment is named repository configuration — the ` +
+        `protection rules and reviewers live on the environment, not in this workflow — so there is ` +
+        `nothing for a blank name to resolve to. Give it the environment's name, or drop the option.`,
+    );
+  }
+  if (environment.url === undefined) return;
+  const url = environment.url.trim();
+  if (url === "") {
+    throw new Error(
+      `${where} "${environment.name}" has an empty \`url\`. Omit the field rather than setting it to "".`,
+    );
+  }
+  if (!/^https?:\/\//.test(url) && !url.includes("${{")) {
+    throw new Error(
+      `${where} "${environment.name}" has \`url: "${environment.url}"\`, which is neither an absolute ` +
+        `http(s) URL nor a \${{ }} expression. GitHub renders this value as the deployment's own link, ` +
+        `so a relative path becomes a dead link on the environment page rather than an error anywhere. ` +
+        `Write the full URL, or an expression the run resolves to one.`,
+    );
+  }
+}
+
 /**
  * Merge a spec's additive `permissions` over the finding-mode's own set
  * (#2242), refusing by name anything that is not strictly additive:
@@ -472,6 +532,18 @@ export function mergePermissions(
   return merged;
 }
 
+/**
+ * Emit a spec's environment as the job's `environment:` mapping. Always the
+ * mapping form, never the `environment: name` string shorthand, so adding a
+ * `url` later is a new key rather than a reshaped value.
+ */
+function environmentDoc(environment: OpEnvironment): Record<string, unknown> {
+  return {
+    name: environment.name,
+    ...(environment.url === undefined ? {} : { url: environment.url }),
+  };
+}
+
 /** Emit one setup entry as a GitHub Actions step. */
 function setupStepDoc(step: OpSetupStep): Record<string, unknown> {
   if ("uses" in step) {
@@ -527,6 +599,7 @@ export function buildGithubOpPipelineDocs(
 
     const setup = spec.setup ?? [];
     assertSetupSteps(spec.name, setup);
+    if (spec.environment) assertEnvironment(spec.name, spec.environment);
 
     // A `push` job is the one that has to survive a gate (#2243): the apply
     // runs with `--gated-exit 0` so a pending approval is a green run, and
@@ -563,6 +636,11 @@ export function buildGithubOpPipelineDocs(
         [jobName]: {
           "runs-on": "ubuntu-latest",
           container: image,
+          // On this Op's own job and never on the notice job beside it: the
+          // notice exists to say a chant gate is pending, and putting it
+          // behind the same reviewer would hold the message back until
+          // somebody had already acted.
+          ...(spec.environment ? { environment: environmentDoc(spec.environment) } : {}),
           ...(gated
             ? {
                 outputs: Object.fromEntries(
@@ -592,6 +670,10 @@ export function buildGithubOpPipelineDocs(
  */
 export function emitOpPipelineYAML(doc: GithubOpPipelineDoc): string {
   const sections: string[] = [];
+  // A dialect's note about what it could not carry (#2257), when there is
+  // one. Absent on github, so an unannotated document is emitted exactly as
+  // it was before the field existed.
+  if (doc.header && doc.header.length > 0) sections.push(doc.header.join("\n"));
   sections.push("on:" + emitYAML(doc.on, 1));
   if (doc.env && Object.keys(doc.env).length > 0) sections.push("env:" + emitYAML(doc.env, 1));
   sections.push("concurrency:" + emitYAML(doc.concurrency, 1));