Skip to content

Commit 686ead2

Browse files
authored
docs: explain org-member review flow for external contributor PRs (#18)
> [!IMPORTANT] > **Merge #16 first.** This PR documents the requester-authorized review flow for external and fork contributor PRs, which only works once #16 (`feat(review-pr): authorize review_requested via the requester for external contributors`) lands. Merging this ahead of #16 would describe a flow that does not yet function and would briefly contradict the on-main defense-in-depth text that #16 updates. ## Summary Documents the UX for org members handling external and fork contributor PRs across three docs. The flow, with no special commands or workflow inputs: 1. An org member approves the workflow run (GitHub gates Actions on PRs from first-time and external contributors). 2. An org member requests a review from `docker-agent` via the native review-request UI (PR sidebar, Reviewers). | File | Change | | --- | --- | | `review-pr/README.md` | New `External and fork contributor PRs` section with the full two-step flow | | `CONTRIBUTING.md` | New `Automated PR Review` section (org members vs external and fork contributors) | | `README.md` | One-line pointer and link in the PR Review Workflow section | ## Alignment with open PRs | PR | Relationship | | --- | --- | | #16 | Source of the documented behavior. The review is authorized by the requesting org member, not the PR author. This PR's wording matches that model. | | #13 | Compatible. The "only triage or write access can request a reviewer" phrasing matches #13's GitHub-native enforcement framing. | ## Conflict avoidance Changes are additive. The new section in `review-pr/README.md` is inserted before `Customizing`, outside the regions #16 and #13 edit (the "What you get" trigger table and the defense-in-depth blockquote), so it merges cleanly against both. ## Validation | Check | Result | | --- | --- | | Merges cleanly against #16 and #13 (additive, non-overlapping regions) | yes | | Em-dash, double-hyphen, or emoji in added prose | none | | Cross-file anchor links resolve (`#external-and-fork-contributor-prs`) | yes | | Markdown lists, links, and backticks valid | yes |
1 parent 70b6d7b commit 686ead2

3 files changed

Lines changed: 27 additions & 0 deletions

File tree

CONTRIBUTING.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,17 @@ cd tests
3838
- Update docs if needed
3939
- Be responsive to feedback
4040

41+
## Automated PR Review
42+
43+
This repo uses the `docker-agent` AI reviewer on pull requests. How a review is triggered depends on who opened the PR:
44+
45+
- **Org members:** request a review from `docker-agent` in the PR sidebar (Reviewers → add `docker-agent`). The review starts automatically once requested.
46+
- **External / fork contributors:** the same request step applies, but GitHub gates Actions on these PRs, so an org member must also approve the workflow run first:
47+
1. **Approve the workflow run.** GitHub holds workflows on PRs from first-time and external contributors until a maintainer clicks **Approve and run workflows**.
48+
2. **Request the review.** In the PR sidebar, under **Reviewers**, add `docker-agent`. The review starts and appears as a check run.
49+
50+
No special commands or workflow inputs are needed, and an external contributor cannot trigger a review of their own PR. The deprecated `/review` comment still works, but requesting `docker-agent` as a reviewer is the supported path. See the [PR Review documentation](review-pr/README.md#external-and-fork-contributor-prs) for the full flow.
51+
4152
## Security Issues
4253

4354
**Do not** open public issues for vulnerabilities. Contact maintainers privately first.

README.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -221,6 +221,8 @@ jobs:
221221

222222
For comprehensive documentation on setting up AI-powered PR reviews, including features like automatic reviews, requesting a review from `docker-agent`, feedback learning, and customization options, see the **[PR Review documentation](review-pr/README.md)**.
223223

224+
For external or fork contributor PRs, an org member approves the workflow run and then requests a review from `docker-agent` via GitHub's native review request UI (no special commands or workflow inputs required). See [External and fork contributor PRs](review-pr/README.md#external-and-fork-contributor-prs).
225+
224226
### Manual Trigger with Inputs
225227

226228
```yaml

review-pr/README.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -156,6 +156,20 @@ pull_request:
156156
```
157157
Adds `synchronize` to also trigger on every push to the PR branch. Opt in if your team wants the reviewer to automatically re-examine every update, at the cost of more workflow runs.
158158

159+
### External and fork contributor PRs
160+
161+
> [!NOTE]
162+
> The requester-authorized path below requires the `check-org-membership` update from PR #16 (merge that PR first). Until it ships, membership is checked against the PR author rather than the requesting org member, so requesting `docker-agent` on an external or fork PR is silently skipped.
163+
164+
Auto-review only runs on PRs authored by org members. A PR opened by an external or fork contributor is **not** reviewed automatically. To get one reviewed, an org member drives it through GitHub's native UI in two steps:
165+
166+
1. **Approve the workflow run.** For PRs from first-time and external contributors, GitHub holds all Actions runs until a maintainer approves them (governed by the repository's `Settings` → `Actions` → `General` fork-PR approval policy). Click **Approve and run workflows** on the PR; until then nothing runs, including the PR review trigger.
167+
2. **Request a review from `docker-agent`.** In the PR sidebar, under **Reviewers**, add `docker-agent`. This fires a `review_requested` event and starts the review, shown as a check run (if `checks: write` is granted).
168+
169+
That is the entire flow. **No special commands or workflow inputs are needed**: not the deprecated `/review` comment, not `workflow_dispatch`, and no caller-side configuration. The review is authorized by the requesting org member rather than the PR author, which is what lets an external contributor's PR be reviewed on demand. The request is safe by construction: GitHub only lets users with triage or write access request a reviewer, and the reusable workflow verifies org membership before any review work runs. An external contributor cannot trigger a review of their own PR.
170+
171+
To re-run the review after new commits, re-request the review from `docker-agent` in the sidebar (the refresh icon next to their name).
172+
159173
### Customizing
160174

161175
```yaml

0 commit comments

Comments
 (0)