Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

ci: review-app approval clears the code gate for write-access authors (#7628)

Cindy Zhang3fb6d7ff2e28
diff --git a/.github/REVIEW_GATE.md b/.github/REVIEW_GATE.md
index 6b05b5e048..a963811e30 100644
--- a/.github/REVIEW_GATE.md
+++ b/.github/REVIEW_GATE.md
@@ -19,6 +19,16 @@ neutral yellow "waiting" signal, not a red failure).
- **Design review is advisory** — it labels the PR and requests design owners,
but does not block the merge.
- An entitled owner's **approval clears the gate automatically** (no manual step).
+- **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
+ latest approval from the review app named in the `REVIEW_APP` repository
+ variable on the exact current head clears the gate. A later request for
+ changes or dismissal from the app, a new commit, or an engineering owner's
+ request for changes on that head makes it pending again. Authors without write
+ access, including fork contributors, still need an engineering owner's
+ approval. If `REVIEW_APP` is unset or the permission cannot be read, the app's
+ reviews have no effect.
## Spec records
@@ -97,11 +107,12 @@ CI and never gain this auto-merge path.
## Sources of truth
-| File | Meaning |
-| ------------------------------- | --------------------------------------------------------------------------- |
-| `.github/ENGOWNERS` | Engineering team. Self-serve **code** and approve every spec kind. |
-| `.github/DESIGNOWNERS` | Design team. Self-serve **design** and approve visual specs. Checked first. |
-| `.github/CODEOWNERS` (`*` line) | Who can **clear** the code gate (and native review requirement). |
+| File | Meaning |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `.github/ENGOWNERS` | Engineering team. Self-serve **code** and approve every spec kind. |
+| `.github/DESIGNOWNERS` | Design team. Self-serve **design** and approve visual specs. Checked first. |
+| `.github/CODEOWNERS` (`*` line) | Who can **clear** the code gate (and native review requirement). |
+| `REVIEW_APP` repository variable | The review app (exact `name[bot]` login) whose exact-head approval clears the code gate for write-access authors. Unset disables it. |
Author bucket is resolved in order: **design owner → eng owner → contributor.**
A handle in `DESIGNOWNERS` is treated as a design owner even if also an eng
@@ -149,6 +160,8 @@ internal contributors' PRs. Owners still self-serve their own domain.
resolve author bucket (DESIGNOWNERS → ENGOWNERS → contributor)
detect high-risk / design from changed paths (lab filtered out)
read reviews → codeApproved / designApproved
+ (code: ENGOWNER approval, or REVIEW_APP's latest exact-head
+ verdict approving when the author has write/admin permission)
effective gate = detected/contributor gate AND NOT owner AND NOT approved
→ labels: needs:code-review · needs:design-review (advisory) · community
→ request reviewers: CODEOWNERS (code) · DESIGNOWNERS (design)
@@ -162,21 +175,25 @@ internal contributors' PRs. Owners still self-serve their own domain.
│ review-clear.yml (workflow_run, base token) │ ← works for fork PRs
└─────────────────────────────────────────────┘
resolve the PR by the run's head_branch (head_sha points at main here)
- entitled CODEOWNER approved?
+ entitled CODEOWNER approved, or REVIEW_APP approved a write-access author?
→ drop needs:code-review · status → success 🟢 · neutralize stale check
+ effective changes requested / dismissed (owner, or the app for a
+ write-access author), or an app-cleared gate no longer qualifies?
+ → status → pending 🟡 · restore needs:code-review
③ branch protection on main
required status context "review-required": pending blocks, success allows
- + 1 required approving review (native)
- ⇒ blocks non-admin merges even for write-access internal contributors
+ ⇒ blocks non-admin merges until the status is success
```
## Enforcement
-`review-required` is a **required status check** on `main`, plus the native
-"1 approving review" requirement. Because a required check blocks non-admin
-merges regardless of write access, this holds internal contributors who have
-write but are not owners. (Repo admins can still bypass.)
+`review-required` is a **required status check** on `main`; no native
+approving-review count is required, so the status alone is the review gate.
+Because a required check blocks non-admin merges regardless of write access, a
+write-access author who is not an owner still needs an engineering owner's
+approval or the review app's exact-head approval. (Repo admins can still
+bypass.)
`spec-owner-approval` must be a required status context on `main` as well. It is
published on every PR — `success` when no knowledge records changed — so
diff --git a/.github/scripts/review-clear-workflow.test.mjs b/.github/scripts/review-clear-workflow.test.mjs
index e948299226..9cd8a17718 100644
--- a/.github/scripts/review-clear-workflow.test.mjs
+++ b/.github/scripts/review-clear-workflow.test.mjs
@@ -50,6 +50,14 @@ const pendingGate = gateStatus(
'Waiting on code review: core runtime change',
);
const clearedGate = gateStatus('success', 'Cleared by code-owner approval.');
+const APP = 'review-app[bot]';
+const APP_CLEARED = 'Cleared by review-app approval for a write-access author.';
+const appClearedGate = gateStatus('success', APP_CLEARED);
+const appReview = (state, commitId = head2) => ({
+ user: {login: APP, type: 'Bot'},
+ state,
+ commit_id: commitId,
+});
const ungatedSuccess = gateStatus('success', 'No code review required.');
function harness(
@@ -60,6 +68,8 @@ function harness(
moveAfterFirstRead = false,
statusFailure = false,
statuses = [pendingGate],
+ reviewApp = '',
+ permission = 'write',
} = {},
) {
const calls = [];
@@ -68,6 +78,7 @@ function harness(
number: 17,
head: {sha: head2},
base: {sha: oldBaseSha},
+ user: {login: 'author', type: 'User'},
labels: labels.map(name => ({name})),
};
const methods = {
@@ -104,6 +115,11 @@ function harness(
};
},
listCommitStatusesForRef: methods.listCommitStatusesForRef,
+ getCollaboratorPermissionLevel: async ({username}) => {
+ calls.push(`permission:${username}`);
+ if (permission instanceof Error) throw permission;
+ return {data: {permission}};
+ },
createCommitStatus: async input => {
calls.push({type: 'status-attempt', input});
if (statusFailure) throw new Error('persistent status failure');
@@ -134,7 +150,9 @@ function harness(
setFailed: message => calls.push(`failed:${message}`),
warning: message => calls.push(`warning:${message}`),
};
- const processValue = {env: {ENG_OWNERS: '@engineer'}};
+ const processValue = {
+ env: {ENG_OWNERS: '@engineer', REVIEW_APP: reviewApp},
+ };
return {calls, context, core, github, processValue};
}
@@ -337,3 +355,132 @@ describe('review-clear exact-head workflow', () => {
},
);
});
+
+describe('review-clear review-app approval for write-access authors', () => {
+ const statusesOf = calls =>
+ calls.filter(call => call?.type === 'status').map(call => call.input);
+
+ it('clears the gate when the app approves a write-access author on the exact head', async () => {
+ const h = harness([appReview('APPROVED')], {reviewApp: APP});
+
+ await run(h);
+
+ expect(h.calls).toContain('permission:author');
+ expect(statusesOf(h.calls)).toEqual([
+ expect.objectContaining({
+ sha: head2,
+ context: 'review-required',
+ state: 'success',
+ description: APP_CLEARED,
+ }),
+ ]);
+ expect(h.calls).toContainEqual(
+ expect.objectContaining({type: 'remove-label'}),
+ );
+ });
+
+ it('blocks again when the app later requests changes on the exact head', async () => {
+ const h = harness([appReview('APPROVED'), appReview('CHANGES_REQUESTED')], {
+ reviewApp: APP,
+ labels: [],
+ statuses: [appClearedGate],
+ });
+
+ await run(h);
+
+ expect(statusesOf(h.calls)).toEqual([
+ expect.objectContaining({
+ state: 'pending',
+ description: 'Waiting on code review after approval withdrawal.',
+ }),
+ ]);
+ expect(h.calls).toContainEqual(
+ expect.objectContaining({type: 'add-label'}),
+ );
+ });
+
+ it.each(['read', 'triage', 'none'])(
+ 'leaves a %s-permission author waiting on an engineering owner',
+ async permission => {
+ const h = harness([appReview('APPROVED')], {reviewApp: APP, permission});
+
+ await run(h);
+
+ expect(mutations(h.calls)).toEqual([]);
+ },
+ );
+
+ it('still clears a no-write author through an engineering-owner approval', async () => {
+ const h = harness([appReview('APPROVED'), review('APPROVED')], {
+ reviewApp: APP,
+ permission: 'read',
+ });
+
+ await run(h);
+
+ expect(statusesOf(h.calls)).toEqual([
+ expect.objectContaining({
+ state: 'success',
+ description: 'Cleared by code-owner approval.',
+ }),
+ ]);
+ });
+
+ it('does not let an app approval of an earlier head clear the new head', async () => {
+ const h = harness([appReview('APPROVED', head1)], {reviewApp: APP});
+
+ await run(h);
+
+ expect(mutations(h.calls)).toEqual([]);
+ });
+
+ it('fails closed when the author permission cannot be read', async () => {
+ const h = harness([appReview('APPROVED')], {
+ reviewApp: APP,
+ permission: new Error('503'),
+ });
+
+ await run(h);
+
+ expect(mutations(h.calls)).toEqual([]);
+ expect(h.calls).toContainEqual(
+ expect.stringContaining('warning:Could not read author permission'),
+ );
+ });
+
+ it('restores an app-cleared gate when the app path no longer applies', async () => {
+ const h = harness([appReview('APPROVED')], {
+ reviewApp: APP,
+ permission: new Error('503'),
+ labels: [],
+ statuses: [appClearedGate],
+ });
+
+ await run(h);
+
+ expect(statusesOf(h.calls)).toEqual([
+ expect.objectContaining({state: 'pending'}),
+ ]);
+ });
+
+ it('ignores app reviews when REVIEW_APP is unset', async () => {
+ const h = harness([appReview('APPROVED')]);
+
+ await run(h);
+
+ expect(h.calls).not.toContain('permission:author');
+ expect(mutations(h.calls)).toEqual([]);
+ });
+
+ it("keeps an engineering owner's exact-head request for changes over an app approval", async () => {
+ const h = harness([review('CHANGES_REQUESTED'), appReview('APPROVED')], {
+ reviewApp: APP,
+ });
+
+ await run(h);
+
+ expect(statusesOf(h.calls)).toEqual([
+ expect.objectContaining({state: 'pending'}),
+ ]);
+ });
+});
diff --git a/.github/scripts/review-signal-decision.cjs b/.github/scripts/review-signal-decision.cjs
index 678df652a6..81e6bccac9 100644
--- a/.github/scripts/review-signal-decision.cjs
+++ b/.github/scripts/review-signal-decision.cjs
@@ -38,8 +38,34 @@ function classifyReviewSignalPaths(changedFiles) {
return {files, hasSafeBoundaryRename, paths};
}
-function resolveReviewApprovals({reviews, headSha, engOwners, designOwners}) {
+// GitHub's collaborator-permission API reports `admin`, `write`, `read`, or
+// `none`; maintain and custom write-based roles report `write`. Anything else,
+// including a missing or malformed response, is not write access.
+function hasWritePermission(permissionResponse) {
+ const permission = permissionResponse?.permission;
+ return permission === 'admin' || permission === 'write';
+}
+
+// The review app is configured by its exact GitHub login (for example
+// `name[bot]`). An unset or malformed value disables the review-app path.
+function normalizeReviewApp(value) {
+ const login = String(value ?? '')
+ .trim()
+ .toLowerCase();
+ return /^[a-z0-9][a-z0-9-]*\[bot\]$/.test(login) ? login : '';
+}
+
+function resolveReviewApprovals({
+ reviews,
+ headSha,
+ engOwners,
+ designOwners,
+ reviewApp = '',
+ authorHasWrite = false,
+}) {
+ const app = normalizeReviewApp(reviewApp);
const latestByUser = new Map();
+ let appState = null;
for (const review of reviews) {
const login = review.user?.login?.toLowerCase();
if (
@@ -50,15 +76,21 @@ function resolveReviewApprovals({reviews, headSha, engOwners, designOwners}) {
) {
continue;
}
+ if (app && login === app) {
+ // Only the app itself can author a review under its `[bot]` login, but
+ // also require GitHub's Bot account type so a lookalike never counts.
+ if (review.user?.type === 'Bot') appState = review.state;
+ continue;
+ }
latestByUser.set(login, review.state);
}
- let codeApproved = false;
+ let ownerApproved = false;
let designApproved = false;
- let codeWithdrawn = false;
+ let ownerWithdrawn = false;
for (const [login, state] of latestByUser) {
if (state === 'APPROVED') {
- if (engOwners.includes(login)) codeApproved = true;
+ if (engOwners.includes(login)) ownerApproved = true;
if (designOwners.includes(login)) designApproved = true;
continue;
}
@@ -66,18 +98,33 @@ function resolveReviewApprovals({reviews, headSha, engOwners, designOwners}) {
(state === 'CHANGES_REQUESTED' || state === 'DISMISSED') &&
engOwners.includes(login)
) {
- codeWithdrawn = true;
+ ownerWithdrawn = true;
}
}
+
+ // The review app decides the engineering gate only for a write-access
+ // author, only by its latest exact-head verdict, and never over an
+ // engineering owner's exact-head request for changes.
+ const appCounts = Boolean(app) && authorHasWrite === true;
+ const appApproved = appCounts && appState === 'APPROVED' && !ownerWithdrawn;
+ const appWithdrawn =
+ appCounts && (appState === 'CHANGES_REQUESTED' || appState === 'DISMISSED');
+ const codeApproved = ownerApproved || appApproved;
+ let codeApprovedBy = null;
+ if (ownerApproved) codeApprovedBy = 'owner';
+ else if (appApproved) codeApprovedBy = 'review-app';
return {
codeApproved,
- codeWithdrawn: !codeApproved && codeWithdrawn,
+ codeApprovedBy,
+ codeWithdrawn: !codeApproved && (ownerWithdrawn || appWithdrawn),
designApproved,
};
}
module.exports = {
classifyReviewSignalPaths,
+ hasWritePermission,
isSafeSpace,
+ normalizeReviewApp,
resolveReviewApprovals,
};
diff --git a/.github/scripts/review-signal-decision.test.mjs b/.github/scripts/review-signal-decision.test.mjs
index f6552acbfb..59f9618019 100644
--- a/.github/scripts/review-signal-decision.test.mjs
+++ b/.github/scripts/review-signal-decision.test.mjs
@@ -8,6 +8,8 @@ import {describe, expect, it} from 'vitest';
const require = createRequire(import.meta.url);
const {
classifyReviewSignalPaths,
+ hasWritePermission,
+ normalizeReviewApp,
resolveReviewApprovals,
} = require('./review-signal-decision.cjs');
@@ -18,6 +20,22 @@ const approval = (login, commitId, state = 'APPROVED') => ({
commit_id: commitId,
state,
});
+const APP = 'review-app[bot]';
+const appReview = (commitId, state = 'APPROVED') => ({
+ user: {login: APP, type: 'Bot'},
+ commit_id: commitId,
+ state,
+});
+const resolveWithApp = (reviews, {authorHasWrite = true, ...rest} = {}) =>
+ resolveReviewApprovals({
+ reviews,
+ headSha: head2,
+ engOwners: ['engineer'],
+ designOwners: ['designer'],
+ reviewApp: APP,
+ authorHasWrite,
+ ...rest,
+ });
describe('review-signal exact-head approvals', () => {
it('does not let an H1 engineering approval clear H2', () => {
@@ -30,6 +48,7 @@ describe('review-signal exact-head approvals', () => {
}),
).toEqual({
codeApproved: false,
+ codeApprovedBy: null,
codeWithdrawn: false,
designApproved: false,
});
@@ -45,6 +64,7 @@ describe('review-signal exact-head approvals', () => {
}),
).toEqual({
codeApproved: false,
+ codeApprovedBy: null,
codeWithdrawn: false,
designApproved: false,
});
@@ -64,6 +84,7 @@ describe('review-signal exact-head approvals', () => {
}),
).toEqual({
codeApproved: true,
+ codeApprovedBy: 'owner',
codeWithdrawn: false,
designApproved: true,
});
@@ -82,6 +103,7 @@ describe('review-signal exact-head approvals', () => {
}),
).toEqual({
codeApproved: false,
+ codeApprovedBy: null,
codeWithdrawn: true,
designApproved: false,
});
@@ -101,6 +123,7 @@ describe('review-signal exact-head approvals', () => {
}),
).toEqual({
codeApproved: true,
+ codeApprovedBy: 'owner',
codeWithdrawn: false,
designApproved: false,
});
@@ -168,3 +191,117 @@ describe('review-signal exact-head approvals', () => {
expect(typeof mod.exports.resolveReviewApprovals).toBe('function');
});
});
+
+describe('review-app approval for write-access authors', () => {
+ it('clears the code gate for a write-access author on the exact head', () => {
+ expect(resolveWithApp([appReview(head2)])).toEqual({
+ codeApproved: true,
+ codeApprovedBy: 'review-app',
+ codeWithdrawn: false,
+ designApproved: false,
+ });
+ });
+
+ it('blocks again when a later exact-head verdict requests changes or is dismissed', () => {
+ for (const state of ['CHANGES_REQUESTED', 'DISMISSED']) {
+ expect(
+ resolveWithApp([appReview(head2), appReview(head2, state)]),
+ ).toEqual({
+ codeApproved: false,
+ codeApprovedBy: null,
+ codeWithdrawn: true,
+ designApproved: false,
+ });
+ }
+ });
+
+ it('clears again when the latest exact-head verdict approves after a request for changes', () => {
+ expect(
+ resolveWithApp([appReview(head2, 'CHANGES_REQUESTED'), appReview(head2)])
+ .codeApprovedBy,
+ ).toBe('review-app');
+ });
+
+ it('ignores a later app comment, which is not a verdict', () => {
+ expect(
+ resolveWithApp([appReview(head2), appReview(head2, 'COMMENTED')])
+ .codeApproved,
+ ).toBe(true);
+ });
+
+ it('still needs an engineering owner when the author lacks write access', () => {
+ expect(resolveWithApp([appReview(head2)], {authorHasWrite: false})).toEqual(
+ {
+ codeApproved: false,
+ codeApprovedBy: null,
+ codeWithdrawn: false,
+ designApproved: false,
+ },
+ );
+ expect(
+ resolveWithApp([appReview(head2), approval('engineer', head2)], {
+ authorHasWrite: false,
+ }).codeApprovedBy,
+ ).toBe('owner');
+ });
+
+ it('does not carry an app approval of an earlier head to a new head', () => {
+ expect(resolveWithApp([appReview(head1)])).toEqual({
+ codeApproved: false,
+ codeApprovedBy: null,
+ codeWithdrawn: false,
+ designApproved: false,
+ });
+ });
+
+ it("keeps an engineering owner's exact-head request for changes over an app approval", () => {
+ expect(
+ resolveWithApp([
+ approval('engineer', head2, 'CHANGES_REQUESTED'),
+ appReview(head2),
+ ]),
+ ).toEqual({
+ codeApproved: false,
+ codeApprovedBy: null,
+ codeWithdrawn: true,
+ designApproved: false,
+ });
+ });
+
+ it('ignores the app when REVIEW_APP is unset or malformed', () => {
+ for (const reviewApp of ['', undefined, 'not-a-bot', ' ']) {
+ expect(resolveWithApp([appReview(head2)], {reviewApp}).codeApproved).toBe(
+ false,
+ );
+ }
+ });
+
+ it('ignores a non-Bot account that matches the configured login', () => {
+ expect(
+ resolveWithApp([
+ {user: {login: APP, type: 'User'}, commit_id: head2, state: 'APPROVED'},
+ ]).codeApproved,
+ ).toBe(false);
+ });
+
+ it('treats only write and admin as write access', () => {
+ expect(hasWritePermission({permission: 'admin'})).toBe(true);
+ expect(hasWritePermission({permission: 'write'})).toBe(true);
+ for (const response of [
+ {permission: 'read'},
+ {permission: 'none'},
+ {permission: 'triage'},
+ {},
+ null,
+ undefined,
+ ]) {
+ expect(hasWritePermission(response)).toBe(false);
+ }
+ });
+
+ it('normalizes the configured app login and rejects non-bot values', () => {
+ expect(normalizeReviewApp(' Review-App[bot] ')).toBe('review-app[bot]');
+ expect(normalizeReviewApp('review-app')).toBe('');
+ expect(normalizeReviewApp(undefined)).toBe('');
+ });
+});
diff --git a/.github/scripts/review-signal-workflow.test.mjs b/.github/scripts/review-signal-workflow.test.mjs
index 970dc7e39c..a2a4037161 100644
--- a/.github/scripts/review-signal-workflow.test.mjs
+++ b/.github/scripts/review-signal-workflow.test.mjs
@@ -33,6 +33,8 @@ async function runSignal({
backfill = false,
helperMissing = false,
reviews = [],
+ reviewApp = '',
+ permission = 'write',
} = {}) {
const pr = {
number: 42,
@@ -84,7 +86,14 @@ async function runSignal({
listReviews: async () => ({data: reviews}),
requestReviewers: mutations.requestReviewers,
},
- repos: {getContent, createCommitStatus: mutations.createCommitStatus},
+ repos: {
+ getContent,
+ createCommitStatus: mutations.createCommitStatus,
+ getCollaboratorPermissionLevel: vi.fn(async () => {
+ if (permission instanceof Error) throw permission;
+ return {data: {permission}};
+ }),
+ },
issues: {
addLabels: mutations.addLabels,
removeLabel: mutations.removeLabel,
@@ -121,6 +130,7 @@ async function runSignal({
...parsed.env,
ENG_OWNERS: '@engineer',
DESIGN_OWNERS: '@designer',
+ REVIEW_APP: reviewApp,
},
},
Buffer,
@@ -333,3 +343,108 @@ describe('review-signal appearance-only contract', () => {
);
});
});
+
+describe('review-signal review-app approval for write-access authors', () => {
+ const APP = 'review-app[bot]';
+ const appReview = (state, commitId = HEAD) => ({
+ user: {login: APP, type: 'Bot'},
+ state,
+ commit_id: commitId,
+ });
+ const gateStatus = mutations =>
+ mutations.createCommitStatus.mock.calls.map(([input]) => ({
+ state: input.state,
+ description: input.description,
+ }));
+
+ it('clears a write-access author whose exact head the app approved', async () => {
+ const {mutations, github} = await runSignal({
+ eventName: 'pull_request_target',
+ reviews: [appReview('APPROVED')],
+ reviewApp: APP,
+ });
+
+ expect(
+ github.rest.repos.getCollaboratorPermissionLevel,
+ ).toHaveBeenCalledWith({
+ owner: 'facebook',
+ repo: 'astryx',
+ username: 'contributor',
+ });
+ expect(gateStatus(mutations)).toEqual([
+ {
+ state: 'success',
+ description:
+ 'Cleared by review-app approval for a write-access author.',
+ },
+ ]);
+ });
+
+ it('keeps the gate pending when the latest exact-head app verdict requests changes', async () => {
+ const {mutations} = await runSignal({
+ eventName: 'pull_request_target',
+ reviews: [appReview('APPROVED'), appReview('CHANGES_REQUESTED')],
+ reviewApp: APP,
+ });
+
+ expect(gateStatus(mutations)).toEqual([
+ expect.objectContaining({state: 'pending'}),
+ ]);
+ });
+
+ it('keeps a no-write author (including a fork author) waiting on an engineering owner', async () => {
+ const {mutations} = await runSignal({
+ eventName: 'pull_request_target',
+ reviews: [appReview('APPROVED')],
+ reviewApp: APP,
+ permission: 'read',
+ });
+
+ expect(gateStatus(mutations)).toEqual([
+ expect.objectContaining({state: 'pending'}),
+ ]);
+ });
+
+ it('gates a pushed head until the app approves that head', async () => {
+ const OLD_HEAD = '4'.repeat(40);
+ const {mutations} = await runSignal({
+ eventName: 'pull_request_target',
+ reviews: [appReview('APPROVED', OLD_HEAD)],
+ reviewApp: APP,
+ });
+
+ expect(gateStatus(mutations)).toEqual([
+ expect.objectContaining({state: 'pending'}),
+ ]);
+ });
+
+ it('fails closed to the engineering-owner path when permission cannot be read', async () => {
+ const {mutations, core} = await runSignal({
+ eventName: 'pull_request_target',
+ reviews: [appReview('APPROVED')],
+ reviewApp: APP,
+ permission: new Error('503'),
+ });
+
+ expect(gateStatus(mutations)).toEqual([
+ expect.objectContaining({state: 'pending'}),
+ ]);
+ expect(core.warning).toHaveBeenCalledWith(
+ expect.stringContaining('Could not read author permission'),
+ );
+ });
+
+ it('does not read permission or count the app when REVIEW_APP is unset', async () => {
+ const {mutations, github} = await runSignal({
+ eventName: 'pull_request_target',
+ reviews: [appReview('APPROVED')],
+ });
+
+ expect(
+ github.rest.repos.getCollaboratorPermissionLevel,
+ ).not.toHaveBeenCalled();
+ expect(gateStatus(mutations)).toEqual([
+ expect.objectContaining({state: 'pending'}),
+ ]);
+ });
+});
diff --git a/.github/workflows/review-clear.yml b/.github/workflows/review-clear.yml
index 21e67e0e21..80387757e8 100644
--- a/.github/workflows/review-clear.yml
+++ b/.github/workflows/review-clear.yml
@@ -9,6 +9,11 @@
# approver requests changes or their review is dismissed. It never creates a
# gate for a head that review-signal did not mark as code-gated.
#
+# Entitled approvals: any ENGOWNER, or — only when the PR author has write or
+# admin permission — the review app named in vars.REVIEW_APP, judged by its
+# latest exact-head verdict. Statuses are written with this workflow's own
+# token.
+#
# The mutation cannot run on the raw pull_request_review event for fork PRs
# (read-only token → 403). It therefore runs on workflow_run after Review signal
# anchors approved, changes_requested, and dismissed review events from the base
@@ -43,6 +48,7 @@ jobs:
uses: actions/github-script@v9
env:
ENG_OWNERS: ${{ vars.ENGOWNERS }}
+ REVIEW_APP: ${{ vars.REVIEW_APP }}
with:
# See review-signal.yml — a transient 503 on the status POST must not
# be the last word on whether the gate clears.
@@ -51,6 +57,8 @@ jobs:
const { owner, repo } = context.repo;
const run = context.payload.workflow_run;
const CODE = 'needs:code-review';
+ const OWNER_CLEARED = 'Cleared by code-owner approval.';
+ const APP_CLEARED = 'Cleared by review-app approval for a write-access author.';
// Resolve the PR the review belonged to.
//
@@ -137,23 +145,45 @@ jobs:
return;
}
+ // A write- or admin-permission author's gate also follows the review
+ // app's (vars.REVIEW_APP) latest exact-head verdict. Permission is
+ // read live; an unset app or a failed read leaves the app's reviews
+ // without effect.
+ const reviewApp = decision.normalizeReviewApp(process.env.REVIEW_APP);
+ let authorHasWrite = false;
+ if (reviewApp) {
+ try {
+ const { data: permission } =
+ await github.rest.repos.getCollaboratorPermissionLevel({
+ owner, repo, username: full.user.login,
+ });
+ authorHasWrite = decision.hasWritePermission(permission);
+ } catch (e) {
+ core.warning(`Could not read author permission; review-app approval does not apply: ${e.message}`);
+ }
+ }
+
// Resolve the effective exact-head review state with the same
// dependency-free helper review-signal uses. Also read this head's
// latest review-required status: only the existing label or a latest
// status emitted by this gate proves that review-signal owned it.
let codeApproved = false;
+ let codeApprovedBy = null;
let codeWithdrawn = false;
let gateOwned = false;
+ let appClearedStatus = false;
try {
const reviews = await github.paginate(github.rest.pulls.listReviews, {
owner, repo, pull_number: prNumber, per_page: 100,
});
- ({codeApproved, codeWithdrawn} =
+ ({codeApproved, codeApprovedBy, codeWithdrawn} =
decision.resolveReviewApprovals({
reviews,
headSha,
engOwners: [...codeApprovers],
designOwners: [],
+ reviewApp,
+ authorHasWrite,
}));
const statuses = await github.paginate(
@@ -166,13 +196,17 @@ jobs:
const trustedStatus =
latestGateStatus?.creator?.login === 'github-actions[bot]';
const description = latestGateStatus?.description || '';
+ appClearedStatus =
+ trustedStatus &&
+ latestGateStatus.state === 'success' &&
+ description === APP_CLEARED;
const statusOwnsGate =
trustedStatus &&
((latestGateStatus.state === 'pending' &&
(description.startsWith('Waiting on code review:') ||
description === 'Waiting on code review after approval withdrawal.')) ||
(latestGateStatus.state === 'success' &&
- description === 'Cleared by code-owner approval.'));
+ (description === OWNER_CLEARED || appClearedStatus)));
gateOwned =
full.labels.some((label) => label.name === CODE) || statusOwnsGate;
} catch (e) {
@@ -184,8 +218,13 @@ jobs:
core.info(`PR #${prNumber}: current head was not marked as code-gated; leaving it as-is.`);
return;
}
+ // A gate the review app cleared stays clear only while the app path
+ // still approves this head. If it no longer does — the author lost
+ // write access, the permission could not be read, or REVIEW_APP was
+ // unset — restore the pending gate (fail closed).
+ if (!codeApproved && appClearedStatus) codeWithdrawn = true;
if (!codeApproved && !codeWithdrawn) {
- core.info(`PR #${prNumber}: no effective ENGOWNER review-state change; leaving gate as-is.`);
+ core.info(`PR #${prNumber}: no effective review-state change; leaving gate as-is.`);
return;
}
@@ -231,7 +270,8 @@ jobs:
}
await github.rest.repos.createCommitStatus({
owner, repo, sha: headSha, context: 'review-required',
- state: 'success', description: 'Cleared by code-owner approval.',
+ state: 'success',
+ description: codeApprovedBy === 'review-app' ? APP_CLEARED : OWNER_CLEARED,
});
core.info(`review-required status → success on #${prNumber}.`);
// Neutralize stale check-run(s) of the same name so the rollup isn't
@@ -245,7 +285,7 @@ jobs:
await github.rest.checks.update({
owner, repo, check_run_id: cr.id,
conclusion: 'neutral',
- output: { title: 'Superseded by review-required status', summary: 'Cleared by code-owner approval; see the review-required status.' },
+ output: { title: 'Superseded by review-required status', summary: 'Cleared by an entitled approval; see the review-required status.' },
});
core.info(`Neutralized stale check-run ${cr.id} on #${prNumber}.`);
}
diff --git a/.github/workflows/review-signal.yml b/.github/workflows/review-signal.yml
index 4f697cecbc..8f84781aa3 100644
--- a/.github/workflows/review-signal.yml
+++ b/.github/workflows/review-signal.yml
@@ -31,7 +31,9 @@
# The CODE label DISABLES auto-merge so the PR can't merge unattended (the
# design label is advisory and does not). Both are cleared when an entitled
# owner approves (code → CODEOWNER; design → DESIGNOWNER
-# or CODEOWNER). Code detection is path-based and deterministic; design adds a
+# or CODEOWNER). For an author with write or admin permission, the review
+# app named in vars.REVIEW_APP also clears the code gate with its latest
+# approval on the exact head. Code detection is path-based and deterministic; design adds a
# content-based diff score (deterministic too — same diff, same score).
#
# HARD GATE (code review only): this emits a "review-required" COMMIT STATUS.
@@ -110,6 +112,7 @@ jobs:
env:
ENG_OWNERS: ${{ vars.ENGOWNERS }}
DESIGN_OWNERS: ${{ vars.DESIGNOWNERS }}
+ REVIEW_APP: ${{ vars.REVIEW_APP }}
with:
# api.github.com 503s intermittently; an unretried one used to leave a
# PR with no review-required status at all, blocked forever on
@@ -447,24 +450,46 @@ jobs:
// the PR's reviews here (this job runs on pull_request_target and
// workflow_dispatch, both of which work for forks) and treat a gate
// as satisfied when an entitled owner has approved:
- // code gate → an ENGOWNER approval
+ // code gate → an ENGOWNER approval, or — for an author with
+ // write or admin permission — the review app's
+ // (vars.REVIEW_APP) latest verdict, when it approves
// design gate → a DESIGNOWNER approval
// Only reviews whose commit_id equals this current PR head count.
// Within that head, each reviewer's latest APPROVED /
// CHANGES_REQUESTED / DISMISSED state wins. An H1 approval can never
// clear H2 for either engineering or design.
+ //
+ // The author's permission is read live at every evaluation. An unset
+ // REVIEW_APP or a failed read leaves the app's reviews without effect
+ // (fail closed to the engineering-owner path).
+ const reviewApp = reviewDecision.normalizeReviewApp(process.env.REVIEW_APP);
+ let authorHasWrite = false;
+ if (reviewApp && codeHighRisk) {
+ try {
+ const { data: permission } =
+ await github.rest.repos.getCollaboratorPermissionLevel({
+ owner, repo, username: pr.user.login,
+ });
+ authorHasWrite = reviewDecision.hasWritePermission(permission);
+ } catch (e) {
+ core.warning(`Could not read author permission; review-app approval does not apply: ${e.message}`);
+ }
+ }
let codeApproved = false;
+ let codeApprovedBy = null;
let designApproved = false;
try {
const reviews = await github.paginate(github.rest.pulls.listReviews, {
owner, repo, pull_number: pr.number, per_page: 100,
});
- ({codeApproved, designApproved} =
+ ({codeApproved, codeApprovedBy, designApproved} =
reviewDecision.resolveReviewApprovals({
reviews,
headSha: pr.head.sha,
engOwners,
designOwners,
+ reviewApp,
+ authorHasWrite,
}));
} catch (e) {
core.warning(`Could not resolve exact-head reviews: ${e.message}`);
@@ -474,7 +499,7 @@ jobs:
// already approved.
const codeGated = codeHighRisk && !codeApproved;
const designGated = designAffecting && !designApproved;
- core.info(`approvals: code=${codeApproved} design=${designApproved} → codeGated=${codeGated} designGated=${designGated}`);
+ core.info(`approvals: code=${codeApproved} (${codeApprovedBy || '-'}, authorHasWrite=${authorHasWrite}) design=${designApproved} → codeGated=${codeGated} designGated=${designGated}`);
// --- Apply labels. ---
const current = pr.labels.map((l) => l.name);
@@ -578,9 +603,11 @@ jobs:
// backfill; re-run the workflow to retry.
const gateDescription = codeGated
? `Waiting on code review: ${gateReasons.join(', ')}`.slice(0, 140)
- : codeHighRisk && codeApproved
- ? 'Cleared by code-owner approval.'
- : 'No code review required.';
+ : codeHighRisk && codeApprovedBy === 'review-app'
+ ? 'Cleared by review-app approval for a write-access author.'
+ : codeHighRisk && codeApproved
+ ? 'Cleared by code-owner approval.'
+ : 'No code review required.';
await github.rest.repos.createCommitStatus({
owner,
repo,