feat: fork-PR comments via pull_request + workflow_run split (+ checkout@v7 docs hardening) (#142)

## What

Reworks how bumpy gets a release-plan comment onto **fork** PRs. Two
parts:

1. **Docs hardening (original scope):** lead with the unprivileged
`pull_request` check as the default; apply the July-16
`actions/checkout@v7` change (`allow-unsafe-pr-checkout` on the
read-only `./pr` checkout).
2. **New safer fork-comment architecture:** a `pull_request` +
`workflow_run` split where the **privileged half never touches fork code
or files** — added after we audited the residual risks of the
single-file `pull_request_target` approach.

## Why the split

A fork's `pull_request` token is read-only at issuance (enforced
server-side — REST/GraphQL/`gh`/`curl` all 403, no secrets), so the
comment must be posted from a privileged base-repo run. The
`workflow_run` split is the only design where the privileged job has
**no untrusted checkout, no package manager run against fork config, and
reads no fork file** — it just posts pre-rendered text. That removes the
`allow-unsafe-pr-checkout` fragility, the symlink read-surface, the
registry-redirect surface, and the CodeQL dismissal that the
`pull_request_target` workflow carries.

## CLI changes (`@varlock/bumpy`, minor)

- **`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. Still posts directly when it has a
write token (same-repo PRs).
- **`ci comment --body-file <path>`** — posts a pre-rendered body.
**Security-critical:** it resolves the target PR from the **trusted
`workflow_run` event** (`head_sha` → PR lookup), *never* from the
artifact (which is fork-influenced), and treats the body as data. Sets
`GH_REPO` from `GITHUB_REPOSITORY` so it runs without a checkout. No-ops
on a missing/empty body.

## User-facing setup

The fork-comment setup is **optional** — only needed to show the comment
on PRs from forks (the check itself already runs red/green on forks).
Add `--emit-comment` + `upload-artifact` to your existing `pull_request`
CI, and drop in a small `workflow_run` poster. Docs: [`Commenting on
fork
PRs`](https://github.com/dmno-dev/bumpy/blob/claude/adoring-buck-35a83a/docs/github-actions.md#commenting-on-fork-prs).
The `pull_request_target` approach has been **removed** from the docs —
the split is the only documented fork-comment path.

## Dogfood

Replaced our `pull_request_target` `bumpy-check.yaml` (two jobs) with a
single `pull_request` check that emits + uploads, plus a new
`bumpy-comment.yaml` (`workflow_run`) that builds main's bumpy and
posts.

## Tests / verification

- New `test/core/ci-comment.test.ts`: `resolveTargetPrNumber` derives
the PR from the event `head_sha` (and ignores a hostile `#999` in the
body); `ci comment` no-ops on missing/empty body. Full suite: **389
pass**, typecheck + lint + fmt clean.
- Smoke-tested `--emit-comment` (writes a real rendered `comment.md`)
and `ci comment` (no-op + error paths) end-to-end.

## ⚠️ One-time bootstrapping note

On *this* PR, the new dogfood `bumpy-comment.yaml` (which builds
**main's** bumpy) will fail, because `ci comment` doesn't exist on
`main` until this merges. That's cosmetic — it's the poster workflow,
not the PR check, and this PR's own comment still posts directly from
`bumpy-check.yaml` (same-repo write token). It goes green automatically
once merged.

Author: theoephraim

.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.

.github/workflows/bumpy-check.yaml

@@ -1,69 +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:
-      - uses: actions/checkout@v6
+      - 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@v6
-        with:
-          ref: main
-          persist-credentials: false
-      # UNTRUSTED PR head into ./pr — only READ via --cwd, never built or run.
-      - uses: actions/checkout@v6
+      - uses: actions/upload-artifact@v4
+        if: always() # upload even when the check fails — the comment explains why
         with:
-          ref: ${{ github.event.pull_request.head.sha }}
-          path: pr
-          persist-credentials: false
-      - 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

.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 }}

.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 ⬅️

docs/cli.md

@@ -184,18 +184,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.