@intentius/chant-lexicon-github 0.124.57 → 0.124.59

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AAEH,OAAO,EAaL,KAAK,WAAW,EACjB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAmB9F,OAAO,EAAsB,KAAK,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAEtF,yFAAyF;AACzF,eAAO,MAAM,cAAc,YAAW,CAAC;AAEvC,oEAAoE;AACpE,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1F;AAED,4DAA4D;AAC5D,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9F;AAED,qEAAqE;AACrE,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,sBAAsB,EAC/B,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAA;CAAO,GAC7C;IAAE,GAAG,EAAE,mBAAmB,CAAC;IAAC,IAAI,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAAC,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAA;CAAE,CAgGpI;AAoID,4EAA4E;AAC5E,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,sBAAsB,GAAG,qBAAqB,CAMvH"}
+{"version":3,"file":"generate-op-waves-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-waves-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AAEH,OAAO,EAaL,KAAK,WAAW,EACjB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAmB9F,OAAO,EAAsB,KAAK,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAEtF,yFAAyF;AACzF,eAAO,MAAM,cAAc,YAAW,CAAC;AAEvC,oEAAoE;AACpE,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1F;AAED,4DAA4D;AAC5D,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9F;AAED,qEAAqE;AACrE,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,sBAAsB,EAC/B,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAA;CAAO,GAC7C;IAAE,GAAG,EAAE,mBAAmB,CAAC;IAAC,IAAI,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAAC,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAA;CAAE,CAiGpI;AAoID,4EAA4E;AAC5E,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,sBAAsB,GAAG,qBAAqB,CAMvH"}

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

@@ -98,7 +98,8 @@ export function buildGithubOpWavesDoc(spec, options, dialect = {}) {
     const forge = dialect.forge ?? "github";
     const product = resolveProductWords(options.words ?? {}).product;
     const image = options.image ?? OP_WAVES_IMAGE;
-    const byReview = spec.waves.some((w) => w.approval === "pr-review");
+    // `approvals.preview` reads the merged pull request from the forge, as a pr-review wave does.
+    const byReview = spec.approvals?.preview === true || spec.waves.some((w) => w.approval === "pr-review");
     // #4630: a pr-review or pull-request wave gets the plans workflow and its approval status.
     const statusBeforeMerge = opWavesPostsApprovalStatus(spec);
     for (const wave of spec.waves) {

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

@@ -1 +1 @@
-{"version":3,"file":"generate-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,oCAAoC,CAAC;AA2CjG,OAAO,KAAK,EACV,oBAAoB,IAAI,YAAY,EACpC,wBAAwB,IAAI,qBAAqB,EACjD,uBAAuB,IAAI,oBAAoB,EAEhD,MAAM,0BAA0B,CAAC;AAGlC,YAAY,EAAE,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,CAAC;AAE1E;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,6FAA6F;IAC7F,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5B,mIAAmI;IACnI,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,uEAAuE;IACvE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,0DAA0D;IAC1D,IAAI,EAAE,YAAY,EAAE,CAAC;CACtB;AAkoBD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAWpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GAClC,iBAAiB,CA+JnB;AA4CD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CAGtB"}
+{"version":3,"file":"generate-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,oCAAoC,CAAC;AA6CjG,OAAO,KAAK,EACV,oBAAoB,IAAI,YAAY,EACpC,wBAAwB,IAAI,qBAAqB,EACjD,uBAAuB,IAAI,oBAAoB,EAEhD,MAAM,0BAA0B,CAAC;AAGlC,YAAY,EAAE,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,CAAC;AAE1E;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,6FAA6F;IAC7F,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5B,mIAAmI;IACnI,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,uEAAuE;IACvE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,0DAA0D;IAC1D,IAAI,EAAE,YAAY,EAAE,CAAC;CACtB;AA6qBD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAWpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GAClC,iBAAiB,CA+JnB;AA4CD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CAGtB"}

package/dist/components/generate-pipeline.js

@@ -61,7 +61,7 @@ import { GATED_WAVE_RECORD, gatedWaveJobs } from "@intentius/chant/components/ga
 import { CI_IMAGE, ciJobName, dirnameOf, fillCommand, GITHUB_JOB_TOKEN, GITHUB_RUNNER, githubRunsOn } from "@intentius/chant/ci-jobs";
 import { CHECKOUT_TOKEN_ENV, checkoutScript, dropForgeTokens, handoverOutputs, handoverTrap, takeOverScript } from "@intentius/chant/ci-handover";
 import { OIDC_REQUEST_VARS, TRADE_SPEC_ENV, tradeLine } from "@intentius/chant/ci-identity";
-import { prApplyComment, GREEN_TAG_PATTERN, GREEN_TICK_WORKFLOW, PR_APPLY_RECORD, PR_LOOP_REPORT_DIR, prApplyGroup, prRecordGroup, prApplyRecordKey, prApplyWaveJobName, prLoopJobs, prLoopPostJob, prLoopSetup, PR_PLAN_NOTE_JOB, PR_LOCK_JOB, PR_UNLOCK_JOB, prUnlockCommand, prLockCommand, prCommentLockJobs, prCommentPreviewJob, PREVIEW_REF_ENV, PREVIEW_HEAD_OUTPUT, prLoopWaveJobs, prLoopWithWaves, prEnvJobs, prLoopJobStage, prStaleJob, PR_STALE_JOB, prLoopRunner, PR_ENV_REPORT_DIR, PR_ENV_SWEEP_CRON, PR_ENV_POST_JOB, } from "@intentius/chant/components/pr-pipeline";
+import { prApplyComment, GREEN_TAG_PATTERN, GREEN_TICK_WORKFLOW, PR_APPLY_RECORD, PR_LOOP_REPORT_DIR, prApplyGroup, prRecordGroup, prApplyRecordKey, prApplyWaveJobName, prLoopJobs, prLoopPostJob, prLoopSetup, PR_PLAN_NOTE_JOB, PR_LOCK_JOB, PR_UNLOCK_JOB, prUnlockCommand, prLockCommand, prCommentLockJobs, prCommentPreviewJob, prActionJob, prLoopPassedEnv, PREVIEW_REF_ENV, PREVIEW_HEAD_OUTPUT, prLoopWaveJobs, prLoopWithWaves, prEnvJobs, prLoopJobStage, prStaleJob, PR_STALE_JOB, prLoopRunner, PR_ENV_REPORT_DIR, PR_ENV_SWEEP_CRON, PR_ENV_POST_JOB, } from "@intentius/chant/components/pr-pipeline";
 import { forgejoRepoLockLines, REPO_APPLY_GROUP } from "@intentius/chant/components/repo-lock";
 import { memberRepoPath } from "@intentius/chant/lexicon";
 import { productStatusContext, resolveProductWords } from "@intentius/chant/ci-product-words";
@@ -239,7 +239,10 @@ function prLoopGithubDoc(components, env, image, beforeScript, extraScript, opti
     ];
     // #4168 step 9: under apply on merge the apply runs on a green signal, and a push to the branch records.
     const forgejo = loop.forge === "forgejo";
-    const onGreen = forgejo ? "startsWith(github.ref, 'refs/tags/ci/green/')" : "github.event_name == 'workflow_run' || github.event_name == 'workflow_dispatch'";
+    // #4654: the action job answers its comment and a dispatch that names an action; such a dispatch starts no apply.
+    const action = prActionJob(loop.forge ?? "github", loop);
+    const plainDispatch = action ? `(github.event_name == 'workflow_dispatch' && github.event.inputs.${action.inputs.action} == '')` : "github.event_name == 'workflow_dispatch'";
+    const onGreen = forgejo ? "startsWith(github.ref, 'refs/tags/ci/green/')" : `github.event_name == 'workflow_run' || ${plainDispatch}`;
     const onPush = loop.applyOnMerge && forgejo ? "github.event_name == 'push' && startsWith(github.ref, 'refs/heads/')" : "github.event_name == 'push'";
     // #4301: a `/chant apply` comment on a pull request starts the apply before merge. GitHub also asks for a commenter who can write.
     const onComment = [
@@ -467,6 +470,34 @@ function prLoopGithubDoc(components, env, image, beforeScript, extraScript, opti
             },
         }
         : {};
+    // #4654: `/<product> <action word> <member> <action>`, or a dispatch naming both, runs the product's action verb at the target branch's commit.
+    const actionJobs = action
+        ? {
+            [action.jobName]: {
+                if: [
+                    `(github.event_name == 'workflow_dispatch' && github.event.inputs.${action.inputs.action} != '')`,
+                    `(${[
+                        "github.event_name == 'issue_comment'",
+                        `startsWith(github.event.comment.body, '${action.comment.replace(/'/g, "''")} ')`,
+                        ...(forgejo ? [] : ["contains(fromJSON('[\"OWNER\",\"MEMBER\",\"COLLABORATOR\"]'), github.event.comment.author_association)"]),
+                    ].join(" && ")})`,
+                ].join(" || "),
+                "runs-on": GITHUB_RUNNER,
+                container: image,
+                // One action of a pipeline at a time, and never two runs of one request.
+                concurrency: concurrency(`chant-action-${env}${member ? `-${member.name}` : ""}`),
+                permissions: withIdToken({ contents: "write", issues: "write", "pull-requests": "write" }),
+                steps: [
+                    ...(identity ? [tradeStep(identity.apply, "apply")] : []),
+                    // An issue_comment run checks out the target branch's commit, a dispatch the ref it names: never a pull request's head.
+                    { name: "Check out the target branch's commit", uses: CHECKOUT, with: { "fetch-depth": 0 } },
+                    ...runSteps(prLoopSetup(image, loop.engineSetup)),
+                    ...runSteps(beforeScript),
+                    { name: "Run the requested action under its gated request", env: { ...prLoopPassedEnv(forgeName, loop), ...action.env }, run: action.script },
+                ],
+            },
+        }
+        : {};
     const jobsDoc = {
         plan: {
             if: closes ? "github.event_name == 'pull_request' && github.event.action != 'closed'" : "github.event_name == 'pull_request'",
@@ -488,6 +519,7 @@ function prLoopGithubDoc(components, env, image, beforeScript, extraScript, opti
         ...lockJobs,
         ...commentLockJobs,
         ...previewJobs,
+        ...actionJobs,
         ...staleJobs,
         ...Object.fromEntries(applyJobs),
         ...Object.fromEntries(controlJobs),
@@ -506,8 +538,18 @@ function prLoopGithubDoc(components, env, image, beforeScript, extraScript, opti
         on.schedule = [{ cron: PR_ENV_SWEEP_CRON }];
     }
     // #4301: a /chant apply comment starts the apply before merge. #4588: and a lock or unlock comment its job.
-    if (loop.applyBeforeMerge || commentLocks.length > 0 || preview)
+    if (loop.applyBeforeMerge || commentLocks.length > 0 || preview || action)
         on.issue_comment = { types: ["created"] };
+    // #4654: a dispatch names a member and an action; both empty, it is the dispatch it was before.
+    if (action) {
+        const input = (description) => ({ description, required: false, type: "string", default: "" });
+        on.workflow_dispatch = {
+            inputs: {
+                [action.inputs.member]: input(`The ${resolveProductWords(loop.words).noun[0]} the action runs on`),
+                [action.inputs.action]: input("The action to run, by its name"),
+            },
+        };
+    }
     // #4625: each job on its stage's runner, the plan side's, the apply side's, or the default.
     if (loop.runners) {
         for (const [name, job] of Object.entries(jobsDoc)) {
@@ -521,7 +563,7 @@ function prLoopGithubDoc(components, env, image, beforeScript, extraScript, opti
         ...(rooted ? {} : { defaults: { run: { "working-directory": member.dir } } }),
         env: { ...options.variables, CHANT_ENV: env },
         jobsDoc,
-        stages: ["plan", PR_PLAN_NOTE_JOB, ...(locks ? [PR_LOCK_JOB, PR_UNLOCK_JOB] : []), ...commentLocks.map((j) => j.jobName), ...(preview ? [preview.jobName, preview.noteJobName] : []), ...(stale ? [PR_STALE_JOB] : []), ...applyNames, ...controlJobs.map(([name]) => name), ...(prEnv ? ["env-up", PR_ENV_POST_JOB, "env-down", "env-sweep"] : [])],
+        stages: ["plan", PR_PLAN_NOTE_JOB, ...(locks ? [PR_LOCK_JOB, PR_UNLOCK_JOB] : []), ...commentLocks.map((j) => j.jobName), ...(preview ? [preview.jobName, preview.noteJobName] : []), ...(action ? [action.jobName] : []), ...(stale ? [PR_STALE_JOB] : []), ...applyNames, ...controlJobs.map(([name]) => name), ...(prEnv ? ["env-up", PR_ENV_POST_JOB, "env-down", "env-sweep"] : [])],
         jobs: [
             { jobName: "plan", component: "pull request plan", stage: "plan", needs: [] },
             { jobName: PR_PLAN_NOTE_JOB, component: "pull request plan note", stage: PR_PLAN_NOTE_JOB, needs: ["plan"] },
@@ -539,6 +581,7 @@ function prLoopGithubDoc(components, env, image, beforeScript, extraScript, opti
                     { jobName: preview.noteJobName, component: "pull request preview comment note", stage: preview.noteJobName, needs: [preview.jobName] },
                 ]
                 : []),
+            ...(action ? [{ jobName: action.jobName, component: "day-2 action", stage: action.jobName, needs: [] }] : []),
             ...applyNames.map((name, i) => ({
                 jobName: name,
                 component: name === "record" ? "merge record" : loop.applyBeforeMerge ? "apply before merge" : loop.waveGate ? `green apply, wave ${i}` : "green apply",

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "eab8cbe3ae719023202bcc5ffdbbbd5ca8dd0d263d22ca405024ff9991cf07b6",
+    "manifest.json": "4066803d139ed6d48a742aaf7871d082dfbd84e20e3b0ce47759310f71ed6bd6",
     "meta.json": "c50e0ef3845c370c3ad2210b8bba455980417c0f818aa6ed46e06d4fb8b1b9f9",
     "types/index.d.ts": "0ead95536e947ddfb98a5acf0ddb88547913b5a53a342df67711c59266f84b3e",
     "rules/deprecated-action-version.ts": "a9ba7cc924ff1c7055110416d8989273690415bfb5e8dcc32dc9431b9351f5ca",
@@ -78,5 +78,5 @@
     "skills/chant-github-patterns.md": "bb3abef289a8fdfcf07d6bb2d7289dcb2f38bc0cb0321ea320b78b45a6f548c0",
     "skills/chant-github-security.md": "aab111cb0871cad30281ce48d7da23663689619351029219e2be019a1a61e394"
   },
-  "composite": "c581b6a6d25abd873cb8aba19d5ccd648c178312acdbdac07a30900b9b685b5a"
+  "composite": "ae39d39910bc91feedb80f2e03a55d960e100010e9afbf71ff3458d0f3491d49"
 }

package/dist/manifest.json

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

package/package.json

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

package/src/components/__golden__/pr-loop-action.github.yml

@@ -0,0 +1,228 @@
+name: chant-pr-prod
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+  workflow_run:
+    workflows:
+      - chant-ci-green
+    types:
+      - completed
+  workflow_dispatch:
+    inputs:
+      stack:
+        description: The stack the action runs on
+        required: false
+        type: string
+        default: ''
+      action:
+        description: The action to run, by its name
+        required: false
+        type: string
+        default: ''
+  issue_comment:
+    types:
+      - created
+
+env:
+  CHANT_ENV: prod
+
+jobs:
+  plan:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    container: node:22
+    permissions:
+      contents: read
+    outputs:
+      report_0: '${{ steps.plan.outputs.report_0 }}'
+    steps:
+      - name: Check out the change
+        env:
+          CHANT_CHECKOUT_TOKEN: '${{ github.token }}'
+        run: |
+          set -eu
+          git config --global --add safe.directory "$PWD" 2>/dev/null || true
+          [ -d .git ] || git init -q .
+          git remote get-url origin >/dev/null 2>&1 || git remote add origin "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY"
+          if [ -n "${CHANT_CHECKOUT_TOKEN:-}" ]; then
+            chant_auth="$(printf 'x-access-token:%s' "$CHANT_CHECKOUT_TOKEN" | base64 | tr -d '\n')"
+            export GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=http.extraheader GIT_CONFIG_VALUE_0="AUTHORIZATION: basic $chant_auth"
+            unset chant_auth
+          fi
+          ref="$GITHUB_REF"
+          want="$GITHUB_SHA"
+          case "$ref" in
+            refs/heads/*) target="refs/remotes/origin/${ref#refs/heads/}" ;;
+            refs/tags/*) target="$ref" ;;
+            refs/*) target="refs/remotes/${ref#refs/}" ;;
+            *) target="refs/remotes/origin/chant-head" ;;
+          esac
+          if git rev-parse -q --verify HEAD >/dev/null; then git clean -ffdxq; fi
+          git -c protocol.version=2 fetch -q --prune --no-recurse-submodules origin '+refs/heads/*:refs/remotes/origin/*' '+refs/tags/*:refs/tags/*' "+$want:$target"
+          git -c protocol.version=2 fetch -q --no-tags origin '+refs/heads/chant/lifecycle:refs/heads/chant/lifecycle' 2>/dev/null || true
+          case "$ref" in
+            refs/heads/*) git checkout -q --force -B "${ref#refs/heads/}" "$target" ;;
+            *) git checkout -q --force --detach "$target" ;;
+          esac
+      - run: |
+          if [ -z "${CHANT_NO_FORGE_TOKEN:-}" ] && [ "${0#*/}" != "$0" ] && [ -f "$0" ] && ! { [ "${0##*/}" = sh ] || [ "${0##*/}" = bash ] || [ "${0##*/}" = dash ]; } && command -v env >/dev/null 2>&1 && command -v sh >/dev/null 2>&1; then exec env -u CHANT_FORGE_TOKEN -u CHANT_GITHUB_TOKEN -u CHANT_FORGEJO_TOKEN -u CHANT_GITLAB_TOKEN -u CHANT_CHECKOUT_TOKEN -u GITHUB_TOKEN -u GH_TOKEN -u FORGEJO_TOKEN -u GITEA_TOKEN -u GITLAB_TOKEN -u CI_JOB_TOKEN -u ACTIONS_RUNTIME_TOKEN CHANT_NO_FORGE_TOKEN=1 sh -e "$0"; fi; unset CHANT_FORGE_TOKEN CHANT_GITHUB_TOKEN CHANT_FORGEJO_TOKEN CHANT_GITLAB_TOKEN CHANT_CHECKOUT_TOKEN GITHUB_TOKEN GH_TOKEN FORGEJO_TOKEN GITEA_TOKEN GITLAB_TOKEN CI_JOB_TOKEN ACTIONS_RUNTIME_TOKEN
+          command -v tofu >/dev/null 2>&1 || (curl -fsSL https://get.opentofu.org/install-opentofu.sh -o /tmp/install-opentofu.sh && sh /tmp/install-opentofu.sh --install-method standalone)
+      - name: Plan the members this pull request reaches
+        id: plan
+        env:
+          BASE_SHA: '${{ github.event.pull_request.base.sha }}'
+          PR_NUMBER: '${{ github.event.pull_request.number }}'
+        run: |
+          if [ -z "${CHANT_NO_FORGE_TOKEN:-}" ] && [ "${0#*/}" != "$0" ] && [ -f "$0" ] && ! { [ "${0##*/}" = sh ] || [ "${0##*/}" = bash ] || [ "${0##*/}" = dash ]; } && command -v env >/dev/null 2>&1 && command -v sh >/dev/null 2>&1; then exec env -u CHANT_FORGE_TOKEN -u CHANT_GITHUB_TOKEN -u CHANT_FORGEJO_TOKEN -u CHANT_GITLAB_TOKEN -u CHANT_CHECKOUT_TOKEN -u GITHUB_TOKEN -u GH_TOKEN -u FORGEJO_TOKEN -u GITEA_TOKEN -u GITLAB_TOKEN -u CI_JOB_TOKEN -u ACTIONS_RUNTIME_TOKEN CHANT_NO_FORGE_TOKEN=1 sh -e "$0"; fi; unset CHANT_FORGE_TOKEN CHANT_GITHUB_TOKEN CHANT_FORGEJO_TOKEN CHANT_GITLAB_TOKEN CHANT_CHECKOUT_TOKEN GITHUB_TOKEN GH_TOKEN FORGEJO_TOKEN GITEA_TOKEN GITLAB_TOKEN CI_JOB_TOKEN ACTIONS_RUNTIME_TOKEN
+          chant_report="$PWD/.chant/pr"
+          chant_handover() { node -e 'const fs=require("fs"),p=require("path"),z=require("zlib");const [dir,out]=process.argv.slice(1);const CHUNK=450000,PARTS=1,NOTE=["pr-plan.json","pr-note.md"];const all={};const walk=(d,r)=>{let n=[];try{n=fs.readdirSync(d).sort()}catch{return}for(const x of n){const f=p.join(d,x),k=r?r+"/"+x:x;let s;try{s=fs.lstatSync(f)}catch{continue}if(s.isDirectory())walk(f,k);else if(s.isFile())all[k]=fs.readFileSync(f).toString("base64")}};walk(dir,"");const pack=(o)=>z.gzipSync(JSON.stringify(o)).toString("base64");let b=pack(all);if(b.length>CHUNK*PARTS){b=pack(Object.fromEntries(Object.entries(all).filter(([k])=>NOTE.includes(k))));if(b.length>CHUNK*PARTS){b=pack({});console.error("chant: the plan report is too large to hand to the note job, even cut to the report and the note; it hands on none of it")}else console.error("chant: the plan report is too large to hand to the note job whole; it hands on pr-plan.json and pr-note.md")}let o="";for(let i=0;i*CHUNK<b.length;i++)o+="report_"+i+"="+b.slice(i*CHUNK,(i+1)*CHUNK)+"\n";fs.appendFileSync(out,o);' "$chant_report" "${GITHUB_OUTPUT:-/dev/null}" || echo "chant: the plan report could not be handed to the note job" >&2; }
+          trap chant_handover EXIT
+          npx --no-install plywood ci run plan --chant "npx --no-install plywood" --in-place --no-push --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --forge github
+  plan-note:
+    needs:
+      - plan
+    if: always() && github.event_name == 'pull_request' && (needs.plan.result == 'success' || needs.plan.result == 'failure')
+    runs-on: ubuntu-latest
+    container: node:22
+    permissions:
+      actions: read
+      contents: read
+      pull-requests: write
+      statuses: write
+    steps:
+      - name: Check out the target branch's commit
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: '${{ github.event.pull_request.base.sha }}'
+      - name: Take the plan report from the plan job
+        run: |
+          set -u
+          node -e 'const fs=require("fs"),p=require("path"),z=require("zlib");const dir=process.argv[1];let b="";for(const l of fs.readFileSync(0,"utf8").split("\n")){if(!l.trim())continue;let s="";try{s=JSON.parse(l)}catch{}if(typeof s==="string")b+=s}if(!b){console.log("chant: the plan job handed on no report");process.exit(0)}let files;try{files=JSON.parse(z.gunzipSync(Buffer.from(b,"base64"),{maxOutputLength:268435456}).toString("utf8"))}catch(e){console.log("chant: the report the plan job handed on does not read: "+e.message);process.exit(0)}if(!files||typeof files!=="object"||Array.isArray(files)){console.log("chant: the report the plan job handed on is not a set of files");process.exit(0)}let n=0;for(const [k,v] of Object.entries(files)){const parts=k.split("/");if(typeof v!=="string"||k.length>1024||parts.some((x)=>!x||x==="."||x===".."||/[\\\x00-\x1f]/.test(x))){console.log("chant: left out "+JSON.stringify(k));continue}try{const f=p.join(dir,...parts);fs.mkdirSync(p.dirname(f),{recursive:true});fs.writeFileSync(f,Buffer.from(v,"base64"));n++}catch(e){console.log("chant: could not write "+JSON.stringify(k)+": "+e.message)}}console.log("chant: took "+n+" report files from the plan job")' .chant/pr <<'END_OF_REPORT'
+          ${{ toJSON(needs.plan.outputs.report_0) }}
+          END_OF_REPORT
+      - name: Keep the plan report
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: chant-pr-plan
+          path: .chant/pr
+          if-no-files-found: ignore
+          include-hidden-files: true
+      - name: Post the plan note and plywood/plan
+        if: always()
+        env:
+          PR_NUMBER: '${{ github.event.pull_request.number }}'
+          HEAD_SHA: '${{ github.sha }}'
+          PLAN_RESULT: '${{ needs.plan.result }}'
+          GITHUB_TOKEN: '${{ github.token }}'
+        run: npx --no-install plywood components pr-post --pr "$PR_NUMBER" --head "$HEAD_SHA" --env prod --output .chant/pr --forge github --result "$PLAN_RESULT"
+  action:
+    if: (github.event_name == 'workflow_dispatch' && github.event.inputs.action != '') || (github.event_name == 'issue_comment' && startsWith(github.event.comment.body, '/plywood action ') && contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association))
+    runs-on: ubuntu-latest
+    container: node:22
+    concurrency:
+      group: chant-action-prod
+      cancel-in-progress: false
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+    steps:
+      - name: Check out the target branch's commit
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - run: command -v tofu >/dev/null 2>&1 || (curl -fsSL https://get.opentofu.org/install-opentofu.sh -o /tmp/install-opentofu.sh && sh /tmp/install-opentofu.sh --install-method standalone)
+      - name: Run the requested action under its gated request
+        env:
+          CHANT_ACTION_COMMENT: '${{ github.event.comment.body }}'
+          CHANT_ACTION_MEMBER: '${{ github.event.inputs.stack }}'
+          CHANT_ACTION: '${{ github.event.inputs.action }}'
+          PR_NUMBER: '${{ github.event.issue.number }}'
+          GITHUB_TOKEN: '${{ github.token }}'
+        run: |
+          set +e
+          npx --no-install plywood action --from-event
+          code="$?"
+          if [ "$code" -eq 3 ]; then echo "The action waits for an approval."; exit 0; fi
+          exit "$code"
+  record:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    container: node:22
+    concurrency:
+      group: chant-record-prod
+      cancel-in-progress: false
+    permissions:
+      contents: write
+      pull-requests: write
+      statuses: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - run: command -v tofu >/dev/null 2>&1 || (curl -fsSL https://get.opentofu.org/install-opentofu.sh -o /tmp/install-opentofu.sh && sh /tmp/install-opentofu.sh --install-method standalone)
+      - name: Record the plan on the merged commit; nothing applies
+        env:
+          BASE_SHA: '${{ github.event.before }}'
+          GITHUB_TOKEN: '${{ github.token }}'
+          CHANT_RUNNER_KEY: '${{ secrets.CHANT_RUNNER_KEY }}'
+        run: |
+          if [ -z "$BASE_SHA" ] || [ "$BASE_SHA" = "0000000000000000000000000000000000000000" ]; then git fetch origin "main" && BASE_SHA="$(git merge-base FETCH_HEAD "$GITHUB_SHA")"; if [ "$BASE_SHA" = "$GITHUB_SHA" ]; then BASE_SHA="$(git rev-parse --verify --quiet "$GITHUB_SHA^" || echo 4b825dc642cb6eb9a060e54bf8d69288fbee4904)"; fi; fi; export BASE_SHA
+          npx --no-install plywood ci run record --chant "npx --no-install plywood" --in-place --base "$BASE_SHA" --env prod --gate pr-apply --forge github
+      - name: Keep the record report
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: chant-pr-record
+          path: .chant/pr
+          if-no-files-found: ignore
+          include-hidden-files: true
+  apply:
+    if: github.event_name == 'workflow_run' || (github.event_name == 'workflow_dispatch' && github.event.inputs.action == '')
+    runs-on: ubuntu-latest
+    container: node:22
+    concurrency:
+      group: chant-apply-prod
+      cancel-in-progress: false
+    permissions:
+      contents: write
+      pull-requests: write
+      statuses: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - run: command -v tofu >/dev/null 2>&1 || (curl -fsSL https://get.opentofu.org/install-opentofu.sh -o /tmp/install-opentofu.sh && sh /tmp/install-opentofu.sh --install-method standalone)
+      - name: Restore the record of an earlier attempt at this commit
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        with:
+          path: .chant/pr-resume/pr-apply.json
+          key: chant-apply-prod-${{ github.sha }}-${{ github.run_id }}-${{ github.run_attempt }}
+          restore-keys: chant-apply-prod-${{ github.sha }}-
+      - name: Apply the newest green commit under the merged changes' approvals
+        env:
+          GITHUB_TOKEN: '${{ github.token }}'
+          CHANT_RUNNER_KEY: '${{ secrets.CHANT_RUNNER_KEY }}'
+        run: |
+          git fetch --quiet --tags origin "+refs/heads/main:refs/remotes/origin/main" && GREEN_SHA="$(npx --no-install plywood ci last-green)" && git checkout --quiet --detach "$GREEN_SHA"
+          npx --no-install plywood ci run apply --chant "npx --no-install plywood" --in-place --env prod --gate pr-apply --forge github
+      - name: Keep the record for a re-run
+        if: always()
+        uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        with:
+          path: .chant/pr-resume/pr-apply.json
+          key: chant-apply-prod-${{ github.sha }}-${{ github.run_id }}-${{ github.run_attempt }}
+      - name: Keep the apply report
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: chant-pr-apply
+          path: .chant/pr
+          if-no-files-found: ignore
+          include-hidden-files: true

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

@@ -60,6 +60,13 @@ describe("generateGithubOpWavesPipeline", () => {
     expect(files[0]!.yaml).toMatch(/permissions:\n\s+contents: write\n\s+pull-requests: read/);
   });
 
+  test("approvals.preview records the head's plans and lets the wave read the merged pull request", () => {
+    const { files } = generateGithubOpWavesPipeline({ ...spec, approvals: { preview: true } }, { specFile: "waves.json" });
+    expect(files.map((f) => f.name)).toEqual([`${spec.name}.yml`, `${spec.name}-plans.yml`]);
+    expect(files[1]!.yaml).toContain("run: chant run wave --spec waves.json --record-plans");
+    expect(files[0]!.yaml).toMatch(/permissions:\n\s+contents: write\n\s+pull-requests: read/);
+  });
+
   test("a wave-level plan and apply, and stage hooks, render the same jobs: chant run wave runs them (#3762)", () => {
     const { plan: _plan, ...rest } = spec;
     const waveLevel: OpWavesSpec = {

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

@@ -135,7 +135,8 @@ export function buildGithubOpWavesDoc(
   const forge = dialect.forge ?? "github";
   const product = resolveProductWords(options.words ?? {}).product;
   const image = options.image ?? OP_WAVES_IMAGE;
-  const byReview = spec.waves.some((w) => w.approval === "pr-review");
+  // `approvals.preview` reads the merged pull request from the forge, as a pr-review wave does.
+  const byReview = spec.approvals?.preview === true || spec.waves.some((w) => w.approval === "pr-review");
   // #4630: a pr-review or pull-request wave gets the plans workflow and its approval status.
   const statusBeforeMerge = opWavesPostsApprovalStatus(spec);
   for (const wave of spec.waves) {

package/src/components/generate-pipeline.ts

@@ -82,6 +82,8 @@ import {
   prLockCommand,
   prCommentLockJobs,
   prCommentPreviewJob,
+  prActionJob,
+  prLoopPassedEnv,
   PREVIEW_REF_ENV,
   PREVIEW_HEAD_OUTPUT,
   prLoopWaveJobs,
@@ -336,7 +338,10 @@ function prLoopGithubDoc(
   ];
   // #4168 step 9: under apply on merge the apply runs on a green signal, and a push to the branch records.
   const forgejo = loop.forge === "forgejo";
-  const onGreen = forgejo ? "startsWith(github.ref, 'refs/tags/ci/green/')" : "github.event_name == 'workflow_run' || github.event_name == 'workflow_dispatch'";
+  // #4654: the action job answers its comment and a dispatch that names an action; such a dispatch starts no apply.
+  const action = prActionJob(loop.forge ?? "github", loop);
+  const plainDispatch = action ? `(github.event_name == 'workflow_dispatch' && github.event.inputs.${action.inputs.action} == '')` : "github.event_name == 'workflow_dispatch'";
+  const onGreen = forgejo ? "startsWith(github.ref, 'refs/tags/ci/green/')" : `github.event_name == 'workflow_run' || ${plainDispatch}`;
   const onPush = loop.applyOnMerge && forgejo ? "github.event_name == 'push' && startsWith(github.ref, 'refs/heads/')" : "github.event_name == 'push'";
   // #4301: a `/chant apply` comment on a pull request starts the apply before merge. GitHub also asks for a commenter who can write.
   const onComment = [
@@ -566,6 +571,34 @@ function prLoopGithubDoc(
         },
       }
     : {};
+  // #4654: `/<product> <action word> <member> <action>`, or a dispatch naming both, runs the product's action verb at the target branch's commit.
+  const actionJobs: Record<string, unknown> = action
+    ? {
+        [action.jobName]: {
+          if: [
+            `(github.event_name == 'workflow_dispatch' && github.event.inputs.${action.inputs.action} != '')`,
+            `(${[
+              "github.event_name == 'issue_comment'",
+              `startsWith(github.event.comment.body, '${action.comment.replace(/'/g, "''")} ')`,
+              ...(forgejo ? [] : ["contains(fromJSON('[\"OWNER\",\"MEMBER\",\"COLLABORATOR\"]'), github.event.comment.author_association)"]),
+            ].join(" && ")})`,
+          ].join(" || "),
+          "runs-on": GITHUB_RUNNER,
+          container: image,
+          // One action of a pipeline at a time, and never two runs of one request.
+          concurrency: concurrency(`chant-action-${env}${member ? `-${member.name}` : ""}`),
+          permissions: withIdToken({ contents: "write", issues: "write", "pull-requests": "write" }),
+          steps: [
+            ...(identity ? [tradeStep(identity.apply, "apply")] : []),
+            // An issue_comment run checks out the target branch's commit, a dispatch the ref it names: never a pull request's head.
+            { name: "Check out the target branch's commit", uses: CHECKOUT, with: { "fetch-depth": 0 } },
+            ...runSteps(prLoopSetup(image, loop.engineSetup)),
+            ...runSteps(beforeScript),
+            { name: "Run the requested action under its gated request", env: { ...prLoopPassedEnv(forgeName, loop), ...action.env }, run: action.script },
+          ],
+        },
+      }
+    : {};
   const jobsDoc: Record<string, unknown> = {
     plan: {
       if: closes ? "github.event_name == 'pull_request' && github.event.action != 'closed'" : "github.event_name == 'pull_request'",
@@ -587,6 +620,7 @@ function prLoopGithubDoc(
     ...lockJobs,
     ...commentLockJobs,
     ...previewJobs,
+    ...actionJobs,
     ...staleJobs,
     ...Object.fromEntries(applyJobs),
     ...Object.fromEntries(controlJobs),
@@ -604,7 +638,17 @@ function prLoopGithubDoc(
     on.schedule = [{ cron: PR_ENV_SWEEP_CRON }];
   }
   // #4301: a /chant apply comment starts the apply before merge. #4588: and a lock or unlock comment its job.
-  if (loop.applyBeforeMerge || commentLocks.length > 0 || preview) on.issue_comment = { types: ["created"] };
+  if (loop.applyBeforeMerge || commentLocks.length > 0 || preview || action) on.issue_comment = { types: ["created"] };
+  // #4654: a dispatch names a member and an action; both empty, it is the dispatch it was before.
+  if (action) {
+    const input = (description: string) => ({ description, required: false, type: "string", default: "" });
+    on.workflow_dispatch = {
+      inputs: {
+        [action.inputs.member]: input(`The ${resolveProductWords(loop.words).noun[0]} the action runs on`),
+        [action.inputs.action]: input("The action to run, by its name"),
+      },
+    };
+  }
   // #4625: each job on its stage's runner, the plan side's, the apply side's, or the default.
   if (loop.runners) {
     for (const [name, job] of Object.entries(jobsDoc) as Array<[string, Record<string, unknown>]>) {
@@ -618,7 +662,7 @@ function prLoopGithubDoc(
     ...(rooted ? {} : { defaults: { run: { "working-directory": member!.dir } } }),
     env: { ...options.variables, CHANT_ENV: env },
     jobsDoc,
-    stages: ["plan", PR_PLAN_NOTE_JOB, ...(locks ? [PR_LOCK_JOB, PR_UNLOCK_JOB] : []), ...commentLocks.map((j) => j.jobName), ...(preview ? [preview.jobName, preview.noteJobName] : []), ...(stale ? [PR_STALE_JOB] : []), ...applyNames, ...controlJobs.map(([name]) => name), ...(prEnv ? ["env-up", PR_ENV_POST_JOB, "env-down", "env-sweep"] : [])],
+    stages: ["plan", PR_PLAN_NOTE_JOB, ...(locks ? [PR_LOCK_JOB, PR_UNLOCK_JOB] : []), ...commentLocks.map((j) => j.jobName), ...(preview ? [preview.jobName, preview.noteJobName] : []), ...(action ? [action.jobName] : []), ...(stale ? [PR_STALE_JOB] : []), ...applyNames, ...controlJobs.map(([name]) => name), ...(prEnv ? ["env-up", PR_ENV_POST_JOB, "env-down", "env-sweep"] : [])],
     jobs: [
       { jobName: "plan", component: "pull request plan", stage: "plan", needs: [] },
       { jobName: PR_PLAN_NOTE_JOB, component: "pull request plan note", stage: PR_PLAN_NOTE_JOB, needs: ["plan"] },
@@ -636,6 +680,7 @@ function prLoopGithubDoc(
             { jobName: preview.noteJobName, component: "pull request preview comment note", stage: preview.noteJobName, needs: [preview.jobName] },
           ]
         : []),
+      ...(action ? [{ jobName: action.jobName, component: "day-2 action", stage: action.jobName, needs: [] }] : []),
       ...applyNames.map((name, i) => ({
         jobName: name,
         component: name === "record" ? "merge record" : loop.applyBeforeMerge ? "apply before merge" : loop.waveGate ? `green apply, wave ${i}` : "green apply",

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

@@ -0,0 +1,67 @@
+/**
+ * The action job (#4654): with `actionJob`, the pull request loop's
+ * workflow answers `/<product> <action word> <member> <action>` and a
+ * dispatch with the member and action inputs, at the target branch's
+ * commit, through the product's action verb. A dispatch that names an
+ * action starts no apply.
+ */
+
+import { describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { generateGithubPipeline } from "./generate-pipeline";
+
+const ESTATE: DriverComponent[] = [
+  { name: "shop", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "pulumi-up", stack: "shop/prod-us" }] }] },
+];
+
+const WORDS = { product: "plywood", noun: ["stack", "stacks"] as [string, string], commands: { preview: "plan" as const, action: "action" as const }, bin: "npx --no-install plywood" };
+
+interface Step { name?: string; uses?: string; run?: string; env?: Record<string, string>; with?: Record<string, unknown> }
+interface Job { if?: string; needs?: string[]; permissions: Record<string, string>; steps: Step[] }
+type Doc = { on: Record<string, unknown>; jobs: Record<string, Job> };
+
+const gen = (prLoop: Record<string, unknown>) => generateGithubPipeline(ESTATE, { env: "prod", prLoop }).yaml;
+
+describe("the GitHub workflow's action job", () => {
+  const yaml = gen({ words: WORDS, actionJob: true, applyOnMerge: true });
+  const doc = parseYAML(yaml) as Doc;
+
+  test("a dispatch takes the stack and action inputs, and a comment starts the job too", () => {
+    expect(doc.on.workflow_dispatch).toEqual({
+      inputs: {
+        stack: { description: "The stack the action runs on", required: false, type: "string", default: "" },
+        action: { description: "The action to run, by its name", required: false, type: "string", default: "" },
+      },
+    });
+    expect(doc.on.issue_comment).toEqual({ types: ["created"] });
+    const job = doc.jobs.action!;
+    expect(job.if).toContain("github.event_name == 'workflow_dispatch' && github.event.inputs.action != ''");
+    expect(job.if).toContain("startsWith(github.event.comment.body, '/plywood action ')");
+    expect(job.if).toContain("github.event.comment.author_association");
+  });
+
+  test("the job runs the product's verb at the target branch's commit, with the comment and inputs as variables", () => {
+    const job = doc.jobs.action!;
+    expect(job.steps[0]!.uses).toMatch(/^actions\/checkout@/);
+    expect(job.steps[0]!.with).toEqual({ "fetch-depth": 0 });
+    const run = job.steps.at(-1)!;
+    expect(run.run).toContain("npx --no-install plywood action --from-event");
+    expect(run.env).toMatchObject({ CHANT_ACTION_COMMENT: "${{ github.event.comment.body }}", CHANT_ACTION_MEMBER: "${{ github.event.inputs.stack }}", CHANT_ACTION: "${{ github.event.inputs.action }}" });
+    expect(job.permissions).toEqual({ contents: "write", issues: "write", "pull-requests": "write" });
+  });
+
+  test("a dispatch that names an action starts no apply", () => {
+    expect(doc.jobs.apply!.if).toContain("(github.event_name == 'workflow_dispatch' && github.event.inputs.action == '')");
+  });
+
+  test("without actionJob nothing changes", () => {
+    const plain = parseYAML(gen({ words: { ...WORDS, commands: { preview: "plan" as const } }, applyOnMerge: true })) as Doc;
+    expect(plain.jobs.action).toBeUndefined();
+    expect(plain.on.workflow_dispatch).toEqual({});
+  });
+
+  test("golden", async () => {
+    await expect(yaml).toMatchFileSnapshot("./__golden__/pr-loop-action.github.yml");
+  });
+});