@natjswenson/shipflow 0.2.1 → 0.2.3

package/SKILL.md

@@ -51,30 +51,32 @@ user; the CLI is the only thing that *does*.
    - `"shipflow"` → tell the user no existing branch protection was found and shipflow will own it going forward.
    - `"ambiguous"` → **branch protection exists but no settings-as-code artifact was found** (e.g. hand-configured via the GitHub UI). Do NOT silently pick either value — this is exactly the false-positive failure mode a prior design iteration got wrong. Ask explicitly: *"Branch protection exists on this repo but isn't managed as code — should shipflow take ownership of it, or keep managing it externally even though no artifact was found?"* Record whichever the user picks.
 
-5. **Present the interview summary and write `.github/shipflow.json`.** Before writing anything, show the user the resolved branch names, `requiredChecks`, and `protectionOwner` together in one place and wait for explicit confirmation — this is the checkpoint called out at the top of this section. Then write the config in the target repo (never inside the skill package) using `config.example.json` as the template, with `release.mode: "manual-gate"` (the only implemented mode in this version — see Auto mode, below). Tell the user `.github/shipflow.json` is committed policy and should be `git add`/committed — ideally in the same commit as the rendered auto-merge workflow, once step 9 produces one.
+5. **Resolve `release.releaseCredential` — never default it to `GITHUB_TOKEN`.** The rendered `dev-to-main-automerge.yml`'s `GH_TOKEN` comes from this secret name. A PR auto-merged under `secrets.GITHUB_TOKEN` completes (once checks pass) attributed to the `github-actions[bot]` identity, and GitHub's loop-prevention rule means that bot-attributed merge's `pull_request: closed` event **never triggers this or any other workflow** — so `label-release-pending` silently never runs, and the entire manual-gate release-ask flow never has anything to find. This was confirmed empirically, not theoretically: an otherwise-identical PR merged by a real, PAT-authenticated actor fired the closed-event trigger within 2 seconds; one completed by `GITHUB_TOKEN`-enabled auto-merge fired no run at all, even after 100+ seconds. Ask the user to create a fine-grained PAT (or GitHub App installation token) scoped to this repo with `contents: write` + `pull-requests: write`, and to store it as a repo secret themselves (e.g. `gh secret set <NAME> --repo <owner>/<repo>`, run in *their own* shell so the token value never passes through the agent or the transcript). Record only the secret's *name* in `release.releaseCredential` — never its value.
 
-6. **Show the plan.** Run:
+6. **Present the interview summary and write `.github/shipflow.json`.** Before writing anything, show the user the resolved branch names, `requiredChecks`, `protectionOwner`, and `release.releaseCredential` together in one place and wait for explicit confirmation — this is the checkpoint called out at the top of this section. Then write the config in the target repo (never inside the skill package) using `config.example.json` as the template, with `release.mode: "manual-gate"` (the only implemented mode in this version — see Auto mode, below). Tell the user `.github/shipflow.json` is committed policy and should be `git add`/committed — ideally in the same commit as the rendered auto-merge workflow, once step 10 produces one.
+
+7. **Show the plan.** Run:
    ```
    npx -y @natjswenson/shipflow plan --repo <path>
    ```
-   This prints `{ plan, stateHash }`. Present `plan.creates`/`plan.updates`/`plan.noops` to the user in plain language — what will be created, what will change, what's already correct. **Wait for explicit confirmation before proceeding.** If any entry has `handEditDetected: true`, call it out specifically and ask whether to override (see step 8).
+   This prints `{ plan, stateHash }`. Present `plan.creates`/`plan.updates`/`plan.noops` to the user in plain language — what will be created, what will change, what's already correct. **Wait for explicit confirmation before proceeding.** If any entry has `handEditDetected: true`, call it out specifically and ask whether to override (see step 9).
 
-7. **Dry-run apply** (optional sanity check, same output shape as the real apply but nothing is mutated):
+8. **Dry-run apply** (optional sanity check, same output shape as the real apply but nothing is mutated):
    ```
    npx -y @natjswenson/shipflow apply --repo <path> --dry-run
    ```
 
-8. **Apply for real**, passing the `stateHash` from step 6's plan output as `--expect-state-hash` — this is the TOCTOU guard: if repo state drifted between the plan you showed the user and this call, `apply` refuses to mutate anything and tells you to re-plan.
+9. **Apply for real**, passing the `stateHash` from step 7's plan output as `--expect-state-hash` — this is the TOCTOU guard: if repo state drifted between the plan you showed the user and this call, `apply` refuses to mutate anything and tells you to re-plan.
    ```
-   npx -y @natjswenson/shipflow apply --repo <path> --expect-state-hash <hash-from-step-6>
+   npx -y @natjswenson/shipflow apply --repo <path> --expect-state-hash <hash-from-step-7>
    ```
-   If a `handEditDetected` entry was confirmed for override in step 6, pass `--force <entry-id>` (repeatable — one flag per confirmed entry id, never a blanket override).
+   If a `handEditDetected` entry was confirmed for override in step 7, pass `--force <entry-id>` (repeatable — one flag per confirmed entry id, never a blanket override).
 
-9. **Report the result.** Read `applied`/`skipped`/`errors` from the response. A `skipped` entry can be a deliberate refusal (empty checks, hand-edit) or an environment limitation shipflow can't do anything about (e.g. a deletion-ruleset skipped because the repo is private and not on a paid GitHub tier) — read each `reason` and relay it plainly rather than treating every `skipped` entry the same. If `renderedTemplateHashes` is non-empty, update `.github/shipflow.json`'s `renderedTemplateHashes` field with those values and tell the user to commit the config change *and* the rendered workflow file **together, in the same commit** — a split commit is exactly what causes a false `handEditDetected` on a clean checkout later.
+10. **Report the result.** Read `applied`/`skipped`/`errors` from the response. A `skipped` entry can be a deliberate refusal (empty checks, hand-edit) or an environment limitation shipflow can't do anything about (e.g. a deletion-ruleset skipped because the repo is private and not on a paid GitHub tier) — read each `reason` and relay it plainly rather than treating every `skipped` entry the same. If `renderedTemplateHashes` is non-empty, update `.github/shipflow.json`'s `renderedTemplateHashes` field with those values and tell the user to commit the config change *and* the rendered workflow file **together, in the same commit** — a split commit is exactly what causes a false `handEditDetected` on a clean checkout later.
 
 ## Re-run / audit
 
-Same as steps 1, 6, 7, 8, 9 above, skipping the interview (branch names/checks/protectionOwner are already recorded in `.github/shipflow.json` — read it, don't re-ask, unless the user explicitly says they want to reconfigure). If `plan.creates`/`plan.updates` is non-empty, that's drift since the last apply — show it and confirm before applying, exactly as in first-run setup.
+Same as steps 1, 7, 8, 9, 10 above, skipping the interview (branch names/checks/protectionOwner/releaseCredential are already recorded in `.github/shipflow.json` — read it, don't re-ask, unless the user explicitly says they want to reconfigure). If `plan.creates`/`plan.updates` is non-empty, that's drift since the last apply — show it and confirm before applying, exactly as in first-run setup.
 
 ## Check pending releases (`manual-gate` ask-flow)
 
@@ -106,12 +108,14 @@ This is a **separate, later invocation** from the one that ran the promotion's `
 - **`handEditDetected`:** a template file's on-disk content doesn't match what shipflow last rendered *or* what it would freshly render — someone hand-edited it. Never silently pass `--force` for this; always show the user what changed and get explicit confirmation per entry.
 - **TOCTOU abort:** if `apply` returns a `toctou` error, repo state changed between plan and apply — re-run the plan step, don't retry the same `--expect-state-hash`.
 - **`gh auth` failures:** surface these immediately; branch protection and rulesets need repo-admin scope. Don't proceed partway through a plan on missing auth.
+- **`release.releaseCredential` left as (or defaulted to) `GITHUB_TOKEN`:** auto-merge and the required-check gate still work, but `label-release-pending` will silently never run — a `GITHUB_TOKEN`-attributed auto-merge's `pull_request: closed` event never triggers it, so no promotion will ever surface via `shipflow releases`. This fails silently, not loudly — there's no error to catch it — so it must be caught at setup time (step 5) rather than discovered later. If a user reports "releases never show up," check this first.
 
 ## Security rules
 
 - All `gh`/`git` invocations in the CLI are argv-style (`spawnSync` with an args array, no shell) — never construct a shell command string from user input when extending this skill.
 - `.github/shipflow.json` is committed policy, not secrets — never write credential *values* into it, only the *name* of a secret (`release.releaseCredential`).
 - Never write shipflow's config anywhere other than `.github/shipflow.json` in the target repo.
+- **`renderTemplate` validates every substituted value before writing YAML, and this must never be weakened.** `config.branches.dev`/`main` and `release.releaseCredential` are editable by anyone with repo *write* access (not just the admin who ran setup), yet they land in single-quoted YAML string comparisons and a `${{ secrets.X }}` expression with pure string substitution. An unvalidated branch name containing a quote (e.g. `dev' || 'x'=='x`) makes the auto-merge job's `if:` condition unconditionally true — auto-merge would enable on *any* PR to main, not just genuine dev-branch promotions; a value containing a newline can inject arbitrary new YAML steps into the committed, then-executed workflow. If you add a new substitution token, it needs a validator in `TOKEN_VALIDATORS` before it ships — never assume a config field is pre-sanitized.
 
 ## Edge cases
 

package/bin/shipflow.js

@@ -85,7 +85,12 @@ function cmdPlan(args) {
     releaseCredentialName: config.release?.releaseCredential ?? null,
   });
   const templateSource = readFileSync(TEMPLATE_PATH, 'utf8');
-  const plan = computePlan(repoState, config, templateSource);
+  let plan;
+  try {
+    plan = computePlan(repoState, config, templateSource);
+  } catch (e) {
+    return fail(`plan: ${e.message}`);
+  }
   printJson({ plan, stateHash: repoState.stateHash });
 }
 
@@ -122,7 +127,12 @@ function cmdApply(args) {
     releaseCredentialName: config.release?.releaseCredential ?? null,
   });
   const templateSource = readFileSync(TEMPLATE_PATH, 'utf8');
-  const plan = computePlan(repoState, config, templateSource);
+  let plan;
+  try {
+    plan = computePlan(repoState, config, templateSource);
+  } catch (e) {
+    return fail(`apply: ${e.message}`);
+  }
 
   // The CLI-level TOCTOU gate: compare the freshly-detected state against
   // what the user confirmed at plan time (--expect-state-hash, captured

package/config.example.json

@@ -12,7 +12,7 @@
     "mode": "manual-gate",
     "tool": "release-please",
     "layout": "manifest",
-    "releaseCredential": "GITHUB_TOKEN"
+    "releaseCredential": "SHIPFLOW_AUTOMERGE_PAT"
   },
   "branchCleanup": {
     "deleteOnMerge": true,

package/lib/plan.mjs

@@ -79,6 +79,11 @@ function computeTemplatePlanEntry(repoState, config, templateSource) {
     devBranch: config.branches.dev,
     mainBranch: config.branches.main,
     mergeFlag: mergeMethodToFlag(config.mergeMethod?.devToMainMethod),
+    // Must be a real PAT/App-installation-token secret name, not
+    // "GITHUB_TOKEN" — see the template's header comment for why a
+    // GITHUB_TOKEN-attributed auto-merge never fires the closed-event
+    // label job at all.
+    releaseCredentialSecret: config.release?.releaseCredential ?? 'GITHUB_TOKEN',
   };
   const renderedContent = renderTemplate(templateSource, params);
   const freshHash = sha256(renderedContent);

package/lib/render.mjs

@@ -14,7 +14,35 @@
 
 const TOKEN_RE = /\{\{(\w+)\}\}/g;
 
-// params: { devBranch, mainBranch, mergeFlag }
+// DEV_BRANCH/MAIN_BRANCH land inside single-quoted YAML string comparisons
+// (`... == '{{DEV_BRANCH}}'`) and RELEASE_CREDENTIAL_SECRET lands inside a
+// `${{ secrets.X }}` GitHub Actions expression — this function does pure
+// string substitution with NO awareness of YAML or GHA-expression grammar,
+// so any of these three params can break out of their quoting context if
+// not validated first. Concretely: devBranch = "dev' || 'x'=='x" renders
+// the auto-merge job's `if:` condition to `... == 'dev' || 'x'=='x'`,
+// which is unconditionally true — enabling auto-merge on ANY pull request
+// to main, not just genuine dev-branch promotions. A value containing a
+// newline in any of the three can inject entirely new YAML keys/steps into
+// the committed, then-executed workflow file. This is not a theoretical
+// input: config.branches.{main,dev} and config.release.releaseCredential
+// come from .github/shipflow.json, a file anyone with repo WRITE access
+// (not just the admin who ran shipflow's setup) can edit — a strictly
+// lower trust level than the admin-scoped `gh` credential the rendered
+// workflow runs with. Found via a Siege security audit (2026-07-15).
+const UNSAFE_YAML_STRING_RE = /['\r\n]/;
+// GitHub Actions secret names: letters, digits, underscore; cannot start
+// with a digit (case-insensitivity aside, this is the full safe charset).
+const SAFE_SECRET_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+const TOKEN_VALIDATORS = Object.freeze({
+  DEV_BRANCH: (v) => !UNSAFE_YAML_STRING_RE.test(v),
+  MAIN_BRANCH: (v) => !UNSAFE_YAML_STRING_RE.test(v),
+  MERGE_FLAG: () => true, // closed enum from mergeMethodToFlag — never attacker-shaped
+  RELEASE_CREDENTIAL_SECRET: (v) => SAFE_SECRET_NAME_RE.test(v),
+});
+
+// params: { devBranch, mainBranch, mergeFlag, releaseCredentialSecret }
 // mergeFlag is one of "--merge" | "--squash" | "--rebase", derived from
 // config.mergeMethod.devToMainMethod by the caller (not this function —
 // mapping method name -> gh flag is a config-schema concern, kept out of
@@ -22,17 +50,28 @@ const TOKEN_RE = /\{\{(\w+)\}\}/g;
 // config shape, only of the template's token names).
 export function renderTemplate(templateSource, params) {
   const missing = [];
+  const unsafe = [];
   const rendered = templateSource.replace(TOKEN_RE, (_, name) => {
     const key = TOKEN_TO_PARAM[name];
     if (!key || !(key in params)) {
       missing.push(name);
       return `{{${name}}}`;
     }
-    return String(params[key]);
+    const value = String(params[key]);
+    const validate = TOKEN_VALIDATORS[name];
+    if (validate && !validate(value)) {
+      unsafe.push(name);
+    }
+    return value;
   });
   if (missing.length > 0) {
     throw new Error(`renderTemplate: missing param(s) for token(s): ${missing.join(', ')}`);
   }
+  if (unsafe.length > 0) {
+    throw new Error(
+      `renderTemplate: unsafe value for token(s): ${unsafe.join(', ')} — branch names must not contain a quote or newline, and the release-credential secret name must match GitHub's secret-naming rules (letters/digits/underscore, not starting with a digit)`
+    );
+  }
   return rendered;
 }
 
@@ -40,6 +79,7 @@ const TOKEN_TO_PARAM = Object.freeze({
   DEV_BRANCH: 'devBranch',
   MAIN_BRANCH: 'mainBranch',
   MERGE_FLAG: 'mergeFlag',
+  RELEASE_CREDENTIAL_SECRET: 'releaseCredentialSecret',
 });
 
 export function mergeMethodToFlag(devToMainMethod) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@natjswenson/shipflow",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Scaffold a configurable dev/main branching, auto-merge, branch-cleanup, and release-tagging workflow into any repo",
   "license": "MIT",
   "author": "Nate Swenson",

package/skill-invariants.json

@@ -55,6 +55,16 @@
       "id": "ci-scaffold-never-overwrites",
       "pattern": "[Nn]ever silently overwrite an existing workflow file",
       "rationale": "Agent-driven CI scaffolding (added after 1.00s had no pull_request-triggered CI at all) must never clobber a workflow file that's already there — same confirm-before-write discipline as every other mutation in this skill, applied to a step the CLI itself never touches."
+    },
+    {
+      "id": "release-credential-never-github-token",
+      "pattern": "never default it to `GITHUB_TOKEN`",
+      "rationale": "Found by dogfooding on claude-skills itself (2026-07-15): a PR auto-merged under secrets.GITHUB_TOKEN completes attributed to github-actions[bot], and GitHub's loop-prevention rule means that bot-attributed merge's pull_request:closed event never triggers label-release-pending — the entire manual-gate release-ask flow silently never has anything to find unless releaseCredential names a real PAT."
+    },
+    {
+      "id": "render-template-validates-substitutions",
+      "pattern": "never assume a config field is pre-sanitized",
+      "rationale": "Found by a Siege security audit (2026-07-15): renderTemplate did pure string substitution with zero escaping, so a repo-write-level (not admin-level) edit to .github/shipflow.json's branch names or release.releaseCredential could break out of the rendered YAML's quoting and make the auto-merge job's if: condition unconditionally true, or inject arbitrary new workflow steps — a privilege escalation via the credential the rendered workflow runs with."
     }
   ],
   "cli_commands_referenced": ["detect", "plan", "apply", "releases", "release-dispatch", "rename-default-branch"]

package/templates/dev-to-main-automerge.yml.tmpl

@@ -5,6 +5,19 @@ name: auto-merge {{DEV_BRANCH}} to {{MAIN_BRANCH}}
 # for this file, or shipflow's next apply will refuse to overwrite it
 # (handEditDetected) until an explicit --force is passed. Commit both files
 # together in the same commit.
+#
+# GH_TOKEN uses config.release.releaseCredential, NOT a hardcoded
+# secrets.GITHUB_TOKEN, because of GitHub's loop-prevention rule: a PR
+# auto-merged via `gh pr merge --auto` run under the default GITHUB_TOKEN
+# completes (later, asynchronously, once checks pass) attributed to the
+# github-actions[bot] identity — and a `pull_request: closed` event
+# resulting from that bot-attributed merge does NOT trigger this or any
+# other workflow's `on: pull_request` handlers. Confirmed empirically:
+# an identical PR merged by a real, PAT-authenticated actor fired the
+# closed-event trigger immediately; one completed by GITHUB_TOKEN-enabled
+# auto-merge fired no run at all. releaseCredential must therefore name a
+# real PAT/App-installation-token secret (not GITHUB_TOKEN) for
+# label-release-pending to ever actually run.
 
 on:
   pull_request:
@@ -30,7 +43,7 @@ jobs:
       - name: Enable auto-merge
         run: gh pr merge --auto {{MERGE_FLAG}} "${{ github.event.pull_request.number }}" --repo "${{ github.repository }}"
         env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_TOKEN: ${{ secrets.{{RELEASE_CREDENTIAL_SECRET}} }}
 
   # Fires once, when the promotion PR actually merges (a separate event from
   # the job above, which only *enables* auto-merge). Applies a durable
@@ -49,4 +62,4 @@ jobs:
       - name: Apply release-pending label
         run: gh pr edit "${{ github.event.pull_request.number }}" --add-label release-pending --repo "${{ github.repository }}"
         env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_TOKEN: ${{ secrets.{{RELEASE_CREDENTIAL_SECRET}} }}