An open source design system that's fully customizable and agent ready
TypeScript
docs(review-gate): a fork's held review run never needs approving; pin what waits on it (#9775)
Cindy Zhange4c81f34079f
diff --git a/.github/REVIEW_GATE.md b/.github/REVIEW_GATE.mdindex 1944d4d91f..9c253f6d91 100644--- a/.github/REVIEW_GATE.md+++ b/.github/REVIEW_GATE.md@@ -25,6 +25,13 @@ neutral yellow "waiting" signal, not a red failure).engineering owner who approves a fork pull request also posts`/approve-spec <full-sha>`: the command re-evaluates both halves of`review-required` from the current head, the code review included.+ Only the review-clear reconcile waits on the held review run (it runs when+ that run completes), and the owner command and a dispatch repeat it, so the+ held run never needs approving. GitHub's approve endpoint refuses such a run+ anyway ("This run is not from a fork pull request or queued by the Actions+ bot"). If the command was not posted, an engineering owner can run the+ "Review signal" workflow by hand with that pull request's number, which reads+ the reviews and re-evaluates both halves the same way.- **Write-access authors can also clear it with the review app.** When the PRauthor has write or admin permission on the repository (internalcontributors, including designers and partners who are not owners), thediff --git a/.github/scripts/review-signal-workflow.test.mjs b/.github/scripts/review-signal-workflow.test.mjsindex ee771c198d..cc4363d13c 100644--- a/.github/scripts/review-signal-workflow.test.mjs+++ b/.github/scripts/review-signal-workflow.test.mjs@@ -622,3 +622,91 @@ describe('review-signal review-app approval for write-access authors', () => {]);});});++describe("a fork's held review run blocks nothing the owner command and a dispatch do not repeat (spec:AST-030 FR15)", () => {+ // GitHub can hold a fork's pull_request_review run for approval, and its+ // approve endpoint refuses that run. So every review-signal writer of the+ // gate also runs on the owner command and on a dispatch, which GitHub does+ // not hold, and review-clear's writer, which runs after a review run, is+ // repeated by them.+ const writers = Object.entries(parsed.jobs).filter(+ ([, job]) => job.permissions?.statuses === 'write',+ );++ it('has gate writers, and each runs on the owner command and on a dispatch', () => {+ expect(writers.map(([name]) => name).sort()).toEqual([+ 'flag',+ 'spec-owner',+ ]);+ expect(parsed.on.issue_comment).toBeDefined();+ expect(parsed.on.workflow_dispatch.inputs.pr).toBeDefined();+ for (const [, job] of writers) {+ const condition = job.if.replace(/\s+/g, ' ');+ expect(condition).toContain(+ "startsWith(github.event.comment.body, '/approve-spec')",+ );+ // Neither writer requires a review event to run.+ expect(condition).not.toMatch(+ /^github\.event_name == 'pull_request_review'/,+ );+ }+ expect(parsed.jobs.flag.if).toContain(+ "github.event_name == 'workflow_dispatch'",+ );+ // spec-owner runs on a dispatch that names a pull request.+ expect(parsed.jobs['spec-owner'].if).toContain(+ "(github.event_name != 'workflow_dispatch' || github.event.inputs.pr != '')",+ );+ });++ it("skips a fork's review event in every writer, so a held run blocks no write", () => {+ const flag = parsed.jobs.flag.if.replace(/\s+/g, ' ');+ expect(flag).not.toContain("'pull_request_review'");+ expect(parsed.jobs['spec-owner'].if.replace(/\s+/g, ' ')).toContain(+ "(github.event_name != 'pull_request_review' || github.event.pull_request.head.repo.full_name == github.repository)",+ );+ });++ it('gives the review-event job no token, so nothing waits on its run but the code-half reconcile the command repeats', () => {+ const reviewJobs = Object.entries(parsed.jobs).filter(([, job]) =>+ String(job.if ?? '').includes(+ "github.event_name == 'pull_request_review'",+ ),+ );+ expect(reviewJobs.map(([name]) => name)).toEqual(['review-anchor']);+ expect(parsed.jobs['review-anchor'].permissions).toEqual({});+ });++ it("pins review-clear's writer, the only one that waits on a review run, to that run's completion", () => {+ const clear = YAML.parse(+ fs.readFileSync(+ path.join(root, '.github/workflows/review-clear.yml'),+ 'utf8',+ ),+ );+ expect(clear.on).toEqual({+ workflow_run: {workflows: ['Review signal'], types: ['completed']},+ });+ const clearWriters = Object.entries(clear.jobs).filter(+ ([, job]) => job.permissions?.statuses === 'write',+ );+ expect(clearWriters.map(([name]) => name)).toEqual(['clear']);+ // It reconciles only after a review event's run, which the owner command+ // (flag on issue_comment) and a dispatch (flag on workflow_dispatch) repeat+ // from the same reviews.+ expect(clear.jobs.clear.if).toBe(+ "github.event.workflow_run.event == 'pull_request_review'",+ );+ });++ it('tells owners that only the review-clear reconcile waits on a held review run, and names the dispatch fallback', () => {+ // One line per sentence, whatever the guide's wrapping.+ const gate = fs+ .readFileSync(path.join(root, '.github/REVIEW_GATE.md'), 'utf8')+ .replace(/\s+/g, ' ');+ expect(gate).toContain(+ 'Only the review-clear reconcile waits on the held review run',+ );+ expect(gate).toContain('run the "Review signal" workflow by hand');+ });+});