Skip to content

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.md
index 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 PR
author has write or admin permission on the repository (internal
contributors, including designers and partners who are not owners), the
diff --git a/.github/scripts/review-signal-workflow.test.mjs b/.github/scripts/review-signal-workflow.test.mjs
index 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');
+ });
+});