fix(ci): make Docs AI Review workflow work for fork PRs (#3577)

morningman · web-flow · commit 87bdf2f2c225 · 2026-04-24T14:27:17.000-07:00
## Summary

Fix two related issues in `.github/workflows/docs-ai-review.yml` so that
the Docs AI Review packet + advisory comment works for fork-originated
PRs (which is the common case in this repo).

- **Rerun on push when labeled.** The `pull_request` trigger previously
only listed the `labeled` action, so the workflow ran exactly once when
the `ai-review-docs` label was first applied and did not re-run when the
PR was updated with new commits. Add `synchronize` and `reopened` to the
types list, and gate those two actions on the `ai-review-docs` label
already being present on the PR.
- **Split the advisory comment into a `workflow_run` workflow.** Pull
requests from forks run `pull_request` workflows with a read-only
`GITHUB_TOKEN` regardless of declared `permissions:`, so the inline
comment step could never post on fork PRs and returned 403 on both the
GraphQL `addComment` mutation (via `gh pr comment`) and the REST
`issues/{n}/comments` endpoint. Following the standard GitHub pattern:
- `docs-ai-review.yml` (pull_request trigger) now only prepares the
packet and uploads it, together with a `pr-metadata.json` describing PR
number / head SHA / base SHA / trigger name.
- A new `docs-ai-review-comment.yml` (`workflow_run` trigger) downloads
the artifact from the completed run, parses the metadata, and upserts
the advisory comment via REST. Because `workflow_run` runs in the
base-repo context, its `GITHUB_TOKEN` honors `issues: write` even for
fork PRs.

The comment workflow does not check out or execute any code from the
fork — it only consumes the prebuilt packet and metadata JSON — so it
avoids the footgun usually associated with giving write permissions to
fork-triggered runs.

## Test plan

- [ ] After merge, open a fresh fork PR and add the `ai-review-docs`
label — confirm `Docs AI Review` runs (prepare packet + upload
artifact).
- [ ] Confirm `Docs AI Review Comment` fires via `workflow_run`
afterwards and upserts a comment with the packet metadata.
- [ ] Push a follow-up commit to the same PR — confirm `Docs AI Review`
reruns on `synchronize` because the label is still applied, and the
advisory comment is updated in place (PATCH path).
- [ ] Post `/review-docs` as a COLLABORATOR/MEMBER on a PR — confirm
`Docs AI Review` runs via `issue_comment` and the comment workflow
follows.
- [ ] Remove the label, push again — confirm `Docs AI Review` no longer
runs.
diff --git a/.github/workflows/docs-ai-review-comment.yml b/.github/workflows/docs-ai-review-comment.yml
@@ -0,0 +1,97 @@
+name: Docs AI Review Comment
+
+on:
+  workflow_run:
+    workflows: ["Docs AI Review"]
+    types: [completed]
+
+permissions:
+  contents: read
+  actions: read
+  issues: write
+
+jobs:
+  upsert-advisory-comment:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    if: github.event.workflow_run.conclusion == 'success'
+    steps:
+      - name: Locate review packet artifact
+        id: locate
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RUN_ID: ${{ github.event.workflow_run.id }}
+        run: |
+          artifacts_json=$(gh api \
+            "repos/${{ github.repository }}/actions/runs/${RUN_ID}/artifacts" \
+            --paginate)
+          artifact_name=$(echo "$artifacts_json" \
+            | jq -r '.artifacts[] | select(.name | startswith("docs-ai-review-packet-")) | .name' \
+            | head -n 1)
+          if [ -z "$artifact_name" ]; then
+            echo "No docs-ai-review-packet artifact in run ${RUN_ID}; nothing to comment."
+            echo "found=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "found=true" >> "$GITHUB_OUTPUT"
+            echo "name=$artifact_name" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Download review packet artifact
+        if: steps.locate.outputs.found == 'true'
+        uses: actions/download-artifact@v4
+        with:
+          name: ${{ steps.locate.outputs.name }}
+          path: artifact
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Upsert advisory PR comment
+        if: steps.locate.outputs.found == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          packet=artifact/ai-review-packet.json
+          metadata=artifact/pr-metadata.json
+
+          PR_NUMBER=$(jq -r '.pr_number' "$metadata")
+          HEAD_SHA=$(jq -r '.head_sha' "$metadata")
+          BASE_SHA=$(jq -r '.base_sha' "$metadata")
+          TRIGGER_NAME=$(jq -r '.trigger' "$metadata")
+
+          marker='<!-- docs-ai-review:packet -->'
+          changed_count=$(jq '.changed_files | length' "$packet")
+          high_risk=$(jq -r '.high_risk.required' "$packet")
+          agent_count=$(jq '.review_agents | length' "$packet")
+
+          cat > /tmp/docs-ai-review-comment.md <<EOF
+          $marker
+          Docs AI review packet prepared for this PR.
+
+          - Trigger: \`$TRIGGER_NAME\`
+          - Changed files in packet: \`$changed_count\`
+          - High-risk docs path matched: \`$high_risk\`
+          - Review agents included: \`$agent_count\`
+          - Base SHA: \`$BASE_SHA\`
+          - Head SHA: \`$HEAD_SHA\`
+
+          This MVP uploads the packet as a workflow artifact for advisory AI review. AI findings, when produced, are suggestions only; deterministic governance CI remains the blocking signal.
+          EOF
+
+          existing_comment_id=$(
+            gh api "repos/${{ github.repository }}/issues/${PR_NUMBER}/comments" \
+              --paginate \
+              --jq ".[] | select(.user.type == \"Bot\" and (.body | contains(\"$marker\"))) | .id" \
+              | tail -n 1
+          )
+
+          if [ -n "$existing_comment_id" ]; then
+            gh api \
+              --method PATCH \
+              "repos/${{ github.repository }}/issues/comments/${existing_comment_id}" \
+              -f body="$(cat /tmp/docs-ai-review-comment.md)"
+          else
+            gh api \
+              --method POST \
+              "repos/${{ github.repository }}/issues/${PR_NUMBER}/comments" \
+              -f body="$(cat /tmp/docs-ai-review-comment.md)"
+          fi
diff --git a/.github/workflows/docs-ai-review.yml b/.github/workflows/docs-ai-review.yml
@@ -4,7 +4,7 @@ on:
   issue_comment:
     types: [created]
   pull_request:
-    types: [labeled]
+    types: [labeled, synchronize, reopened]
   workflow_dispatch:
     inputs:
       pr_number:
@@ -42,6 +42,11 @@ jobs:
         github.event_name == 'pull_request' &&
         github.event.action == 'labeled' &&
         github.event.label.name == 'ai-review-docs'
+      ) ||
+      (
+        github.event_name == 'pull_request' &&
+        (github.event.action == 'synchronize' || github.event.action == 'reopened') &&
+        contains(github.event.pull_request.labels.*.name, 'ai-review-docs')
       )
     steps:
       - name: Get PR info
@@ -85,6 +90,9 @@ jobs:
       - name: Prepare docs AI review packet
         env:
           BASE_SHA: ${{ steps.pr.outputs.base_sha }}
+          HEAD_SHA: ${{ steps.pr.outputs.head_sha }}
+          PR_NUMBER: ${{ steps.pr.outputs.number }}
+          TRIGGER_NAME: ${{ github.event_name }}
         run: |
           mkdir -p website-quality-governance/generated
           changed_files=$(git diff --name-only "$BASE_SHA" HEAD | paste -sd, -)
@@ -94,68 +102,19 @@ jobs:
             --output website-quality-governance/generated/ai-review-packet.json
           jq '{schema_version, changed_files, high_risk, review_agents: [.review_agents[].id], sync_groups: [.sync_groups[].sync_group_id]}' \
             website-quality-governance/generated/ai-review-packet.json
+          jq -n \
+            --arg pr_number "$PR_NUMBER" \
+            --arg head_sha "$HEAD_SHA" \
+            --arg base_sha "$BASE_SHA" \
+            --arg trigger "$TRIGGER_NAME" \
+            '{pr_number: $pr_number, head_sha: $head_sha, base_sha: $base_sha, trigger: $trigger}' \
+            > website-quality-governance/generated/pr-metadata.json
 
       - name: Upload review packet artifact
         uses: actions/upload-artifact@v4
         with:
           name: docs-ai-review-packet-${{ steps.pr.outputs.number }}
-          path: website-quality-governance/generated/ai-review-packet.json
+          path: |
+            website-quality-governance/generated/ai-review-packet.json
+            website-quality-governance/generated/pr-metadata.json
           if-no-files-found: error
-
-  upsert-advisory-comment:
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    needs: prepare-docs-ai-review
-    if: needs.prepare-docs-ai-review.result == 'success'
-    permissions:
-      contents: read
-      issues: write
-      pull-requests: read
-    steps:
-      - name: Download review packet artifact
-        uses: actions/download-artifact@v4
-        with:
-          name: docs-ai-review-packet-${{ needs.prepare-docs-ai-review.outputs.pr_number }}
-          path: website-quality-governance/generated
-
-      - name: Upsert advisory PR comment
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          PR_NUMBER: ${{ needs.prepare-docs-ai-review.outputs.pr_number }}
-          HEAD_SHA: ${{ needs.prepare-docs-ai-review.outputs.head_sha }}
-          BASE_SHA: ${{ needs.prepare-docs-ai-review.outputs.base_sha }}
-          TRIGGER_NAME: ${{ github.event_name }}
-        run: |
-          marker='<!-- docs-ai-review:packet -->'
-          changed_count=$(jq '.changed_files | length' website-quality-governance/generated/ai-review-packet.json)
-          high_risk=$(jq -r '.high_risk.required' website-quality-governance/generated/ai-review-packet.json)
-          agent_count=$(jq '.review_agents | length' website-quality-governance/generated/ai-review-packet.json)
-
-          cat > /tmp/docs-ai-review-comment.md <<EOF
-          $marker
-          Docs AI review packet prepared for this PR.
-
-          - Trigger: \`$TRIGGER_NAME\`
-          - Changed files in packet: \`$changed_count\`
-          - High-risk docs path matched: \`$high_risk\`
-          - Review agents included: \`$agent_count\`
-          - Base SHA: \`$BASE_SHA\`
-          - Head SHA: \`$HEAD_SHA\`
-
-          This MVP uploads the packet as a workflow artifact for advisory AI review. AI findings, when produced, are suggestions only; deterministic governance CI remains the blocking signal.
-          EOF
-
-          existing_comment_id=$(
-            gh api repos/${{ github.repository }}/issues/${PR_NUMBER}/comments \
-              --jq ".[] | select(.user.type == \"Bot\" and (.body | contains(\"$marker\"))) | .id" \
-              | tail -n 1
-          )
-
-          if [ -n "$existing_comment_id" ]; then
-            gh api \
-              --method PATCH \
-              repos/${{ github.repository }}/issues/comments/${existing_comment_id} \
-              -f body="$(cat /tmp/docs-ai-review-comment.md)"
-          else
-            gh pr comment "$PR_NUMBER" --body-file /tmp/docs-ai-review-comment.md
-          fi
