@natjswenson/shipflow 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -2,6 +2,60 @@
 
 All notable changes to `@natjswenson/shipflow` are documented here.
 
+## 0.3.3 (2026-08-01) — least-privilege permissions in every rendered workflow
+
+- **Every rendered workflow granted its permissions at the workflow level, so
+  every job in the file got them whether it needed them or not.** zizmor flags
+  this as `excessive-permissions` (High), and it was failing this repo's own
+  `security / workflows` gate on `dev-to-main-automerge.yml`. All six templates
+  now deny by default (`permissions: {}`) and grant per job.
+
+  A workflow-level grant is not just untidy — it silently extends to jobs added
+  later that were never reviewed for it. Scoping is the fix; waiving the rule
+  would have kept the finding *and* the exposure.
+
+- **`contents: write` is dropped from the auto-merge workflows entirely, not
+  moved.** `gh pr merge --auto` only *enables* native auto-merge, which is a
+  pull-requests operation; GitHub performs the merge itself afterwards under its
+  own automation rather than this token. Those workflows now grant
+  `pull-requests: write` to the two jobs that call `gh`, and nothing else.
+
+  Where `release.releaseCredential` names a real PAT (the supported setup), the
+  workflow token's permissions never applied to those steps in the first place.
+  These grants are what matters for a repo that left the credential defaulted to
+  `GITHUB_TOKEN`.
+
+### Fixed
+
+- **The gitflow merge-back workflows could not open their own fallback PR.**
+  `release-merge-back` and `hotfix-merge-back` granted only `contents: write`,
+  but their "on any failure, open a PR for manual resolution" step calls
+  `gh pr create` — which needs `pull-requests: write`. Under a defaulted
+  `GITHUB_TOKEN` that step would have failed exactly when it was needed most:
+  after a merge conflict, with nothing else left to surface it. Found while
+  scoping the permissions above, not by a report.
+
+## 0.3.2 (2026-07-28) — attempted npm-page fix; did NOT work
+
+- **Attempted and failed: making npmjs.com render the README.** 0.3.1 put
+  README.md, LICENSE and CHANGELOG.md into the tarball (verified by downloading
+  the published artifact), which fixed what `npm install` delivers. This release
+  additionally staged those files into the package directory before
+  `npm publish` was invoked, on the theory that npm populates the registry
+  manifest's `readme` field from disk at that point. **It did not work.** After
+  publishing, `npm view <pkg> readme` still returns the literal string
+  `ERROR: No README data found!` for both packages.
+  That field appears to be sticky: it was set once by an early release that had
+  no README, and republishing with one present does not overwrite it. Since
+  npmjs.com only falls back to reading the tarball when the field is *absent*
+  (compare `zod`, which renders fine with none at all), the stale error string
+  keeps winning.
+  The ineffective staging step was reverted in the release workflow; the
+  `prepack` hook stays, because the tarball fix is real and verified. **The npm
+  web page for both packages is still blank** — an open issue, likely needing
+  npm support to clear the cached field.
+  Code unchanged in both skills.
+
 ## 0.3.1 (2026-07-28) — publish the README, LICENSE and CHANGELOG to npm
 
 - **Fixed: the npm package shipped with no README, LICENSE or CHANGELOG.**

package/SKILL.md

@@ -62,7 +62,31 @@ user; the CLI is the only thing that *does*.
 
 4. **Confirm branch names and required checks with the user.** Show `workflows.jobNames` from the detect output as candidate `requiredChecks` (this list is already filtered to jobs from workflows that actually trigger on `pull_request` — a job that only runs on `schedule`/`workflow_dispatch` can never satisfy a required check, so it's never offered as a candidate) and let the user confirm/edit the list. **An empty `requiredChecks` list is a fail-open state, not a valid steady state** — `shipflow apply` will hard-refuse to enable auto-merge with zero required checks (see Error handling below). Don't let the user skip this without understanding that consequence.
 
-   **If the candidate list is empty, offer to scaffold a starter CI workflow yourself** — this is a judgment call for the agent, not something shipflow's CLI does (the CLI stays free of per-language/build-tool logic). Investigate the repo directly (`package.json`, `Cargo.toml`, `project.yml`/`.xcodeproj`, `go.mod`, `pyproject.toml`, or whatever's actually there) and draft a minimal, conservative `pull_request`-triggered build+test workflow. **Never silently overwrite an existing workflow file.** Present the drafted YAML to the user and wait for explicit confirmation before writing it — the same confirm-before-write pattern as everything else in this skill. Say plainly that this is a best-effort starting point inferred from repo structure, not a guarantee it's green on the first run — a required check that never passes blocks every future merge, so the user should watch it actually run successfully before relying on it as a required check. Once it exists, re-run step 1's `detect` (repo state changed) and continue this step with the new job name as a real candidate.
+   **If the candidate list is empty, a CI workflow has to exist before auto-merge
+   can be enabled. Hand that job to the `forge` skill** — authoring and *verifying*
+   workflow YAML is its whole subject, and it does things shipflow never will:
+   it resolves every action ref against the real API (no linter checks that an
+   action exists), validates each `with:` key against the action's own
+   `action.yml`, reports how many majors behind each pin is, and runs actionlint
+   and zizmor before showing you anything. Two skills answering "scaffold me a CI
+   workflow" differently is worse than either answer.
+
+   > Use the forge skill to create a `pull_request`-triggered build+test workflow
+   > for this repo, then come back here with the job name.
+
+   **If forge is not installed**, draft it here instead: investigate the repo
+   directly (`package.json`, `Cargo.toml`, `project.yml`/`.xcodeproj`, `go.mod`,
+   `pyproject.toml`, or whatever's actually there) and write a minimal,
+   conservative `pull_request`-triggered build+test workflow.
+   **Never silently overwrite an existing workflow file.** Present it and wait for
+   explicit confirmation before writing it — the same confirm-before-write pattern
+   as everything else in this skill.
+
+   Either way, say plainly that a fresh workflow is a starting point, not a
+   guarantee it's green on the first run — **a required check that never passes
+   blocks every future merge**, so the user should watch it run successfully
+   before relying on it as one. Once it exists, re-run step 1's `detect` (repo
+   state changed) and continue this step with the new job name as a real candidate.
 
 5. **Resolve `protectionOwner`:**
    - `"external"` → tell the user which settings-as-code artifact was found (`settingsAsCodeArtifact` in the detect output) and that shipflow will defer to it, managing only cleanup/automerge/release, not installing a competing ruleset.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@natjswenson/shipflow",
-  "version": "0.3.1",
+  "version": "0.3.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/templates/dev-main-promotion/dev-to-main-automerge.yml.tmpl

@@ -24,9 +24,18 @@ on:
     types: [opened, reopened, synchronize, closed]
     branches: [{{MAIN_BRANCH}}]
 
-permissions:
-  contents: write
-  pull-requests: write
+# Deny by default at the workflow level, grant per job. A workflow-level grant
+# applies to every job in the file, including ones added later that never
+# needed it — which is why zizmor's excessive-permissions rule flags it, and
+# why the fix is to scope rather than to waive.
+#
+# `contents: write` is dropped entirely, not moved. `gh pr merge --auto` only
+# *enables* native auto-merge, a pull-requests operation; GitHub performs the
+# merge itself afterwards, under its own automation rather than this token. The
+# grants below are what matters when releaseCredential is left as GITHUB_TOKEN
+# — where a real PAT is configured (the supported setup, see above), the
+# workflow token's permissions do not apply to these steps at all.
+permissions: {}
 
 jobs:
   # Enables native GitHub auto-merge on open/reopen/synchronize — this job
@@ -39,6 +48,8 @@ jobs:
       github.event.action != 'closed' &&
       github.event.pull_request.head.ref == '{{DEV_BRANCH}}'
     runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
     steps:
       - name: Enable auto-merge
         run: gh pr merge --auto {{MERGE_FLAG}} "${{ github.event.pull_request.number }}" --repo "${{ github.repository }}"

package/templates/gitflow/hotfix-automerge.yml.tmpl

@@ -24,9 +24,15 @@ on:
     types: [opened, reopened, synchronize, closed]
     branches: [{{MAIN_BRANCH}}]
 
-permissions:
-  contents: write
-  pull-requests: write
+# Deny by default at the workflow level, grant per job. A workflow-level grant
+# applies to every job in the file, including ones added later that never
+# needed it — which is why zizmor's excessive-permissions rule flags it, and
+# why the fix is to scope rather than to waive.
+#
+# `contents: write` is dropped entirely, not moved. `gh pr merge --auto` only
+# *enables* native auto-merge, a pull-requests operation; GitHub performs the
+# merge itself afterwards, under its own automation rather than this token.
+permissions: {}
 
 jobs:
   # Enables native GitHub auto-merge on open/reopen/synchronize — this job
@@ -39,6 +45,8 @@ jobs:
       github.event.action != 'closed' &&
       startsWith(github.event.pull_request.head.ref, '{{HOTFIX_BRANCH_PREFIX}}')
     runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
     steps:
       - name: Enable auto-merge
         run: gh pr merge --auto {{MERGE_FLAG}} "${{ github.event.pull_request.number }}" --repo "${{ github.repository }}"

package/templates/gitflow/hotfix-merge-back.yml.tmpl

@@ -15,8 +15,11 @@ on:
     types: [closed]
     branches: [{{MAIN_BRANCH}}]
 
-permissions:
-  contents: write
+# Deny by default at the workflow level, grant per job — a workflow-level grant
+# applies to every job in the file, including ones added later that never needed
+# it. `contents: write` is genuinely required here (this job pushes a merge
+# commit), so it is scoped to the job rather than dropped.
+permissions: {}
 
 jobs:
   merge-back-to-dev:
@@ -24,6 +27,9 @@ jobs:
       github.event.pull_request.merged == true &&
       startsWith(github.event.pull_request.head.ref, '{{HOTFIX_BRANCH_PREFIX}}')
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
     steps:
       - uses: actions/checkout@v4
         with:

package/templates/gitflow/release-automerge.yml.tmpl

@@ -24,9 +24,15 @@ on:
     types: [opened, reopened, synchronize, closed]
     branches: [{{MAIN_BRANCH}}]
 
-permissions:
-  contents: write
-  pull-requests: write
+# Deny by default at the workflow level, grant per job. A workflow-level grant
+# applies to every job in the file, including ones added later that never
+# needed it — which is why zizmor's excessive-permissions rule flags it, and
+# why the fix is to scope rather than to waive.
+#
+# `contents: write` is dropped entirely, not moved. `gh pr merge --auto` only
+# *enables* native auto-merge, a pull-requests operation; GitHub performs the
+# merge itself afterwards, under its own automation rather than this token.
+permissions: {}
 
 jobs:
   # Enables native GitHub auto-merge on open/reopen/synchronize — this job
@@ -39,6 +45,8 @@ jobs:
       github.event.action != 'closed' &&
       startsWith(github.event.pull_request.head.ref, '{{RELEASE_BRANCH_PREFIX}}')
     runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
     steps:
       - name: Enable auto-merge
         run: gh pr merge --auto {{MERGE_FLAG}} "${{ github.event.pull_request.number }}" --repo "${{ github.repository }}"

package/templates/gitflow/release-merge-back.yml.tmpl

@@ -15,8 +15,11 @@ on:
     types: [closed]
     branches: [{{MAIN_BRANCH}}]
 
-permissions:
-  contents: write
+# Deny by default at the workflow level, grant per job — a workflow-level grant
+# applies to every job in the file, including ones added later that never needed
+# it. `contents: write` is genuinely required here (this job pushes a merge
+# commit), so it is scoped to the job rather than dropped.
+permissions: {}
 
 jobs:
   merge-back-to-dev:
@@ -24,6 +27,9 @@ jobs:
       github.event.pull_request.merged == true &&
       startsWith(github.event.pull_request.head.ref, '{{RELEASE_BRANCH_PREFIX}}')
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
     steps:
       - uses: actions/checkout@v4
         with:

package/templates/github-flow/main-automerge.yml.tmpl

@@ -28,9 +28,15 @@ on:
     types: [opened, reopened, synchronize, closed]
     branches: [{{MAIN_BRANCH}}]
 
-permissions:
-  contents: write
-  pull-requests: write
+# Deny by default at the workflow level, grant per job. A workflow-level grant
+# applies to every job in the file, including ones added later that never
+# needed it — which is why zizmor's excessive-permissions rule flags it, and
+# why the fix is to scope rather than to waive.
+#
+# `contents: write` is dropped entirely, not moved. `gh pr merge --auto` only
+# *enables* native auto-merge, a pull-requests operation; GitHub performs the
+# merge itself afterwards, under its own automation rather than this token.
+permissions: {}
 
 jobs:
   # Enables native GitHub auto-merge on open/reopen/synchronize — this job
@@ -41,6 +47,8 @@ jobs:
   auto-merge:
     if: github.event.action != 'closed'
     runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
     steps:
       - name: Enable auto-merge
         run: gh pr merge --auto {{MERGE_FLAG}} "${{ github.event.pull_request.number }}" --repo "${{ github.repository }}"