docs: split PR preview comment into a separate workflow_run job

Fork PRs use the normal beman workflow. The GITHUB_TOKEN in a
pull_request run from a fork is always read-only, but the workflow_run
event fires code from the BASE branch with write permissions. This is
GitHub's recommended pattern for trusted actions on untrusted PRs.

- docs.yml: remove pull-requests: write (no longer needed); remove the
  inline comment step entirely.
- docs-comment.yml: new workflow triggered by workflow_run on
  "Documentation" completion. Posts/updates the preview comment using a
  write-capable token. Finds the PR by searching for an open PR whose
  head matches the triggering run's head_repository + head_branch, so
  it works for both same-repo and fork PRs.

No fork code executes in docs-comment.yml; only trusted metadata from
the workflow_run context is used.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Author: steve-downey

.github/workflows/docs-comment.yml

@@ -0,0 +1,92 @@
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
+# Posts a PR preview comment after the Documentation workflow completes.
+#
+# This is intentionally a separate workflow from docs.yml.  The
+# `pull_request` event (used in docs.yml) always runs with a read-only
+# GITHUB_TOKEN for fork PRs, so it cannot post comments.  The
+# `workflow_run` event runs code from the BASE branch — never from the
+# fork — and is granted write permissions safely.  No fork code executes
+# here; we only read trusted metadata from the workflow_run context.
+#
+# Reference: https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_run
+
+name: Documentation Preview Comment
+
+on:
+  workflow_run:
+    workflows: ["Documentation"]
+    types: [completed]
+
+permissions:
+  pull-requests: write
+
+jobs:
+  comment:
+    name: Post preview link
+    runs-on: ubuntu-latest
+    # Only comment on PR builds that succeeded.  Push and
+    # workflow_dispatch builds don't have a PR to comment on.
+    if: >
+      github.event.workflow_run.event == 'pull_request' &&
+      github.event.workflow_run.conclusion == 'success'
+
+    steps:
+      - name: Harden the runner (Audit all outbound calls)
+        uses: step-security/harden-runner@8d3c67de8e2fe68ef647c8db1e6a09f647780f40 # v2.19.0
+        with:
+          egress-policy: audit
+
+      - name: Post or update PR preview comment
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const MARKER = '<!-- docs-preview-comment -->'
+            const run = context.payload.workflow_run
+            const runUrl = run.html_url
+            const sha = run.head_sha.slice(0, 7)
+            const body = [
+              MARKER,
+              `📚 **Documentation preview** for \`${sha}\` — [workflow run](${runUrl})`,
+              '',
+              'To review: open the **docs-site** artifact from that run,',
+              'extract the zip, and open `index.html` in a browser.',
+            ].join('\n')
+
+            // Locate the open PR that matches this workflow run's head
+            // branch. For same-repo PRs github.event.pull_request is
+            // available directly; for fork PRs we search by head label.
+            const headLabel = `${run.head_repository.owner.login}:${run.head_branch}`
+            const { data: prs } = await github.rest.pulls.list({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              head: headLabel,
+              state: 'open',
+            })
+            if (prs.length === 0) {
+              core.info(`No open PR found for head ${headLabel}; skipping comment.`)
+              return
+            }
+            const issue_number = prs[0].number
+
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number,
+            })
+            const existing = comments.find(c => c.body.includes(MARKER))
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              })
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number,
+                body,
+              })
+            }

.github/workflows/docs.yml

@@ -15,8 +15,7 @@ jobs:
     name: Build
     runs-on: ubuntu-latest
     permissions:
-      contents: write       # needed for gh-pages deploy on main
-      pull-requests: write  # needed to post the preview comment on PRs
+      contents: write   # needed for gh-pages deploy on main
 
     steps:
       - name: Harden the runner (Audit all outbound calls)
@@ -58,51 +57,6 @@ jobs:
           path: ${{ steps.out.outputs.dir }}/
           retention-days: 14
 
-      # Posts a comment on the PR with a direct link to the workflow run
-      # where the docs-site artifact can be downloaded and inspected.
-      # Uses a hidden marker so the comment is updated (not duplicated) on
-      # each push to the PR branch.
-      # Skip on fork PRs: the GITHUB_TOKEN in a fork PR run is always
-      # read-only regardless of the permissions: block, so the comment
-      # would 403. Only attempt it when the PR is within the same repo.
-      - name: Post or update PR preview comment
-        if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
-        uses: actions/github-script@v7
-        with:
-          script: |
-            const MARKER = '<!-- docs-preview-comment -->'
-            const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`
-            const sha = context.payload.pull_request.head.sha.slice(0, 7)
-            const body = [
-              MARKER,
-              `📚 **Documentation preview** for \`${sha}\` — [workflow run](${runUrl})`,
-              '',
-              'To review: open the **docs-site** artifact from that run,',
-              'extract the zip, and open `index.html` in a browser.',
-            ].join('\n')
-
-            const { data: comments } = await github.rest.issues.listComments({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              issue_number: context.issue.number,
-            })
-            const existing = comments.find(c => c.body.includes(MARKER))
-            if (existing) {
-              await github.rest.issues.updateComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                comment_id: existing.id,
-                body,
-              })
-            } else {
-              await github.rest.issues.createComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                issue_number: context.issue.number,
-                body,
-              })
-            }
-
       - name: Deploy to GitHub Pages
         if: github.ref == 'refs/heads/main' && github.event_name == 'push'
         uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0