From e53c7013bafa6bdf7f348b3029c93c8150c30940 Mon Sep 17 00:00:00 2001 From: Sayt-0 Date: Wed, 24 Jun 2026 23:54:13 +0200 Subject: [PATCH 1/2] docs: explain org-member review flow for external contributor PRs Document the UX for org members handling external and fork contributor PRs: approve the workflow run, then request a review from docker-agent via GitHub's native review-request UI. No special commands or workflow inputs are needed. Additive only (new sections), kept out of the regions PRs #16 and #13 edit, so it merges cleanly against both. Aligns with PR #16's requester-authorized model, which is what enables review of external contributor PRs; that behavior requires PR #16 to land first. --- CONTRIBUTING.md | 11 +++++++++++ README.md | 2 ++ review-pr/README.md | 11 +++++++++++ 3 files changed, 24 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c5409bc..548a111 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,6 +38,17 @@ cd tests - Update docs if needed - Be responsive to feedback +## Automated PR Review + +This repo uses the `docker-agent` AI reviewer on pull requests. How a review is triggered depends on who opened the PR: + +- **Org members:** a review runs automatically when the PR is opened or marked ready for review. Re-request a review from `docker-agent` in the sidebar to re-run it. +- **External / fork contributors:** the PR is not reviewed automatically. An org member gets it reviewed in two steps: + 1. **Approve the workflow run.** GitHub holds workflows on PRs from first-time and external contributors until a maintainer clicks **Approve and run workflows**. + 2. **Request the review.** In the PR sidebar, under **Reviewers**, add `docker-agent`. The review starts and appears as a check run. + +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. + ## Security Issues **Do not** open public issues for vulnerabilities. Contact maintainers privately first. diff --git a/README.md b/README.md index a56bc22..66ff8e8 100644 --- a/README.md +++ b/README.md @@ -221,6 +221,8 @@ jobs: 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)**. +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). + ### Manual Trigger with Inputs ```yaml diff --git a/review-pr/README.md b/review-pr/README.md index 097d327..1a4779f 100644 --- a/review-pr/README.md +++ b/review-pr/README.md @@ -156,6 +156,17 @@ pull_request: ``` 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. +### External and fork contributor PRs + +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: + +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. +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. + +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. + +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). + ### Customizing ```yaml From d4b7ac3c95cd3625ce1954424f81b8c6c7cc35b7 Mon Sep 17 00:00:00 2001 From: Sayt-0 Date: Thu, 25 Jun 2026 18:13:52 +0200 Subject: [PATCH 2/2] docs: address review feedback on external contributor review flow - CONTRIBUTING.md: org-member PRs are not auto-reviewed on open or ready-for-review. The self-review trigger fires only on review_requested, so org members also request a review explicitly; the only difference from external contributors is approving the workflow run. - review-pr/README.md: add a visible note that the requester-authorized path depends on the check-org-membership update from PR #16; without it, membership is checked against the PR author and the review is silently skipped. - review-pr/README.md: caveat the check run with "if checks: write is granted" to match the rest of the doc (the Create check run step uses continue-on-error). --- CONTRIBUTING.md | 4 ++-- review-pr/README.md | 5 ++++- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 548a111..30e7606 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -42,8 +42,8 @@ cd tests This repo uses the `docker-agent` AI reviewer on pull requests. How a review is triggered depends on who opened the PR: -- **Org members:** a review runs automatically when the PR is opened or marked ready for review. Re-request a review from `docker-agent` in the sidebar to re-run it. -- **External / fork contributors:** the PR is not reviewed automatically. An org member gets it reviewed in two steps: +- **Org members:** request a review from `docker-agent` in the PR sidebar (Reviewers → add `docker-agent`). The review starts automatically once requested. +- **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: 1. **Approve the workflow run.** GitHub holds workflows on PRs from first-time and external contributors until a maintainer clicks **Approve and run workflows**. 2. **Request the review.** In the PR sidebar, under **Reviewers**, add `docker-agent`. The review starts and appears as a check run. diff --git a/review-pr/README.md b/review-pr/README.md index 1a4779f..24abe9b 100644 --- a/review-pr/README.md +++ b/review-pr/README.md @@ -158,10 +158,13 @@ Adds `synchronize` to also trigger on every push to the PR branch. Opt in if you ### External and fork contributor PRs +> [!NOTE] +> 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. + 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: 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. -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. +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). 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.