diff --git a/.coderabbit.yaml b/.coderabbit.yaml index 6cf552ed70d..6295dd87893 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -5,6 +5,8 @@ reviews: profile: assertive high_level_summary: false request_changes_workflow: true + path_filters: + - '!apps/website/**' # Without this, a review that never happened (rate limit, internal error) # still reports green, so an unreviewed PR is indistinguishable from a # cleanly reviewed one. diff --git a/.github/workflows/ci-vercel-website-preview.yaml b/.github/workflows/ci-vercel-website-preview.yaml index faa4502cc1e..f0121cd933d 100644 --- a/.github/workflows/ci-vercel-website-preview.yaml +++ b/.github/workflows/ci-vercel-website-preview.yaml @@ -146,6 +146,9 @@ jobs: deploy-production: if: github.event_name == 'push' runs-on: ubuntu-latest + environment: + name: website-production + url: ${{ steps.deploy.outputs.url }} steps: - name: Checkout repository uses: actions/checkout@v7 @@ -210,9 +213,6 @@ jobs: URL=$(vercel deploy --prebuilt --prod --archive=tgz) echo "url=$URL" >> "$GITHUB_OUTPUT" - - name: Add deployment URL to summary - run: echo "**Production:** ${{ steps.deploy.outputs.url }}" >> "$GITHUB_STEP_SUMMARY" - - name: Notify IndexNow of changed pages continue-on-error: true timeout-minutes: 5 diff --git a/.github/workflows/pr-website-auto-approve.yaml b/.github/workflows/pr-website-auto-approve.yaml new file mode 100644 index 00000000000..90e816527de --- /dev/null +++ b/.github/workflows/pr-website-auto-approve.yaml @@ -0,0 +1,62 @@ +# Run the website package's configured delivery lane. +# +# Security boundary: pull_request_target and workflow_run load this workflow, +# the policy, and the engine from the default branch; pull request code is +# never executed. Eligibility rules: docs/architecture/package-delivery-lanes.md. +name: 'PR: Website Fast Lane' + +on: + pull_request_target: + types: + - opened + - reopened + - synchronize + - ready_for_review + - converted_to_draft + - edited + - labeled + - unlabeled + workflow_run: + workflows: + - 'CI: Tests E2E' + - 'CI: Website E2E' + types: [completed] + +permissions: + contents: read + +jobs: + fast-lane: + if: github.event.pull_request || github.event.workflow_run.pull_requests[0] + concurrency: + group: website-fast-lane-${{ github.event.pull_request.number || github.event.workflow_run.pull_requests[0].number }} + cancel-in-progress: false + environment: website-approval + runs-on: ubuntu-latest + timeout-minutes: 5 + steps: + - name: Checkout trusted base automation + uses: actions/checkout@v7 + with: + ref: refs/heads/${{ github.event.repository.default_branch }} + persist-credentials: false + sparse-checkout: | + .nvmrc + tools/cicd/fast-lane + + - uses: actions/setup-node@v6 + with: + node-version-file: .nvmrc + + - name: Approve, queue, or withdraw the website pull request + env: + FAST_LANE: website + FAST_LANE_TOKEN: ${{ secrets.WEBSITE_APPROVAL_TOKEN }} + FAST_LANE_DEFAULT_BRANCH: ${{ github.event.repository.default_branch }} + FAST_LANE_EVENT_ACTION: ${{ github.event.action }} + FAST_LANE_EVENT_ACTOR: ${{ github.triggering_actor }} + FAST_LANE_EVENT_LABEL: ${{ github.event.label.name }} + GITHUB_REPOSITORY: ${{ github.repository }} + PR_HEAD_SHA: ${{ github.event.pull_request.head.sha || github.event.workflow_run.head_sha }} + PR_NUMBER: ${{ github.event.pull_request.number || github.event.workflow_run.pull_requests[0].number }} + run: node tools/cicd/fast-lane/src/run.ts diff --git a/docs/adr/CI-FAST-LANE-0041-path-scoped-policy-approval-lanes.md b/docs/adr/CI-FAST-LANE-0041-path-scoped-policy-approval-lanes.md new file mode 100644 index 00000000000..ebe63f61ee5 --- /dev/null +++ b/docs/adr/CI-FAST-LANE-0041-path-scoped-policy-approval-lanes.md @@ -0,0 +1,81 @@ +# ADR-CI-FAST-LANE-0041: Path-Scoped Policy Approval Lanes + +Date: 2026-10-08 + +## Status + +Proposed + +## Context + +Website changes live in this monorepo, so a copy edit under `apps/website/` waits for the same +full-repository checks and human review as a change to the editor. The website's owners want to +ship website-only changes on their own timeline without weakening the safeguards for the rest of +the repository. + +The `main` ruleset requires one approval, a `comfy_website_devs` approval for `apps/website/**`, +and the `lint-and-format`, `test`, `e2e-status`, and `website-e2e` checks. It dismisses stale +approvals on push and merges through the native merge queue. + +## Decision + +Introduce path-scoped delivery lanes, starting with the website: + +- Each lane is a reviewed entry in `tools/cicd/fast-lane/src/lanes.ts` that names its path + prefixes, trusted authors, operator label, trusted labelers, and hold label. +- `pr-website-auto-approve.yaml` runs the `tools/cicd/fast-lane/` workspace from the default + branch. For an eligible same-repository pull request whose complete changed-file set is inside + the lane, it posts a policy-only approval bound to the exact head with a credential held in a + `main`-restricted environment, then arms native auto-merge or enters the queue. Every later run + re-reads live state and withdraws lane-owned approvals and merge state when the pull request + stops being eligible. +- A non-allowlisted author is eligible only on a trusted operator's `labeled` event for the + current head, and stays eligible only while the label remains applied. +- CodeRabbit skips `apps/website/**` for the trial; human change requests still block the lane. +- Production deploys record a GitHub deployment for their commit; rollback uses Vercel's Instant + Rollback. + +### Alternatives not chosen + +- **A GitHub App or bot identity instead of a personal token.** The trial uses an identity whose + team membership already satisfies the website review rule; moving to an App identity needs that + rule changed first. +- **A ruleset bypass list or CODEOWNERS change.** Either removes review for whole paths instead of + binding each approval to a policy decision on an exact head that can be withdrawn. +- **Keeping CodeRabbit on website files with `request_changes_workflow` disabled.** Its change + requests would still need a human to clear them on every website pull request. +- **Label freshness from timeline order.** Commit timeline entries carry author-controlled dates, + so a backdated push could sort before an older label. +- **One global concurrency group, or groups keyed by commit SHA.** A global group lets unrelated + pull requests cancel a pending hold or label run; SHA-keyed groups let two runs approve and + withdraw the same pull request at once. Runs are grouped per pull request instead. +- **Website-scoped lint and typecheck jobs.** The full typecheck (about 6 minutes) finishes before + the website unit and browser suites, so scoping it does not shorten the time to merge. +- **A deployment marker, staged promotion, and a rollback workflow.** The GitHub deployment record + and Vercel's deployment history already tie production to a commit, and Vercel's Instant Rollback + restores a known deployment. + +## Consequences + +### Positive + +- A trusted author's website-only change can reach the merge queue without waiting for a human + reviewer, and every approval is tied to one head and can be withdrawn. +- The rest of the repository keeps its checks, review rule, and merge queue unchanged. +- Another package can add a lane with one entry and a copy of the workflow. + +### Negative + +- No human reviews a fast-laned diff, and `apps/website/**` includes build configuration and code + that the production build runs with deployment secrets. +- Policy approvals come from a personal account; that account's own manual merge actions after its + first policy review are treated as lane-owned. +- GitHub keeps only the newest pending run per concurrency group, so a pending `labeled` run can be + cancelled by another event on the same pull request; the operator re-runs it or re-applies the + label. +- The trial adds a workflow and an engine that operators must maintain. + +## Notes + +- Engine and operator model: [Package delivery lanes](../architecture/package-delivery-lanes.md). +- Trial runbook: [Website delivery validation](../architecture/website-delivery-validation.md). diff --git a/docs/architecture/package-delivery-lanes.md b/docs/architecture/package-delivery-lanes.md new file mode 100644 index 00000000000..cee3fc4166b --- /dev/null +++ b/docs/architecture/package-delivery-lanes.md @@ -0,0 +1,72 @@ +# Package delivery lanes + +A package delivery lane lets one part of the monorepo choose its own balance of speed and rigor +without weakening the rest of the repository. A lane decides whether every changed path belongs to +the package, applies the package's reviewed approval policy to the exact commit, and then hands the +pull request to the repository's normal checks, merge queue, deployment, and rollback. + +The website is the first lane. The approval engine in the `tools/cicd/fast-lane/` workspace is +package-neutral; the lane entry and the workflow are per lane. + +## The dials a package owns + +Each lane is an entry in `tools/cicd/fast-lane/src/lanes.ts`, written in lowercase. A policy change +receives normal repository review, so changing a dial is visible in history. + +| Dial | Meaning | +| -------------------------- | -------------------------------------------------------------------------------------------- | +| `pathPrefixes` | The complete set of paths the lane is allowed to change. | +| `approval.identity` | The GitHub account whose token posts policy approvals; verified before the lane acts. | +| `approval.trustedAuthors` | Authors who may receive a policy approval without an operator label. | +| `approval.approvalLabel` | An explicit opt-in route for other authors. | +| `approval.trustedLabelers` | Operators allowed to apply that label. | +| `approval.holdLabel` | Stops the lane at its next run: dismisses lane approvals and disarms lane-owned merge state. | + +## Fixed safety rules + +These are implementation invariants, not package dials: + +- The workflow and policy are checked out from the protected default branch. Pull request code is + never executed by the approval workflow. +- Forks, drafts, non-default base branches, stale event heads, incomplete file lists, and paths + outside the lane fail closed. +- Every approval is tied to the exact head SHA. A new commit needs a new policy decision. +- Approval-label provenance is bound to the current workflow event. A non-allowlisted author is + eligible only on the exact-head `labeled` event from a trusted operator; later events continue + while that same head has the policy approval and the label remains applied. Removing the label + withdraws the approval. Commit timestamps are never used as a proxy for push order. +- An active human change request blocks the lane. Comments and pending reviews do not count as + change requests. +- The credential's GitHub identity must match the identity declared in the policy, and it cannot + approve its own pull request. +- If verification or arming fails after the policy approval, every active policy approval is + dismissed. A run whose event head is no longer the pull request head changes nothing; the + repository ruleset dismisses approvals of older heads on push, and the run for the new head + decides again. +- Fast-lane runs for one pull request share a concurrency group, so at most one runs at a time and + GitHub keeps only the newest pending run. Hold and label-removal runs are safe to lose because + every run reads the live labels; a pending `labeled` approval run is not, and the operator + re-runs it or re-applies the label. Compensation attempts merge-state teardown and each active + policy-approval dismissal separately, so one failed API call does not skip the others. +- The lane disables only auto-merge or queue state that its identity enabled at or after its first + policy review on the pull request. Because the identity is a personal account, that includes the + account owner's own merge actions in that window. + +The reusable TypeScript engine lives in `tools/cicd/fast-lane/src/`. `lanes.ts` holds the policies, +`policy.ts` the pure policy decisions, `github.ts` the GitHub transport, and `automation.ts` the +approval and merge lifecycle. Behavioral tests run `runFastLane` against an in-memory GitHub double +and cover each fixed rule. + +## Adding a lane + +1. Add the lane to `tools/cicd/fast-lane/src/lanes.ts`. +2. Copy `pr-website-auto-approve.yaml` and point it at the new lane and at the workflows whose + completion should re-run the lane. +3. Put the approval credential in a package-specific protected environment and restrict that + environment to the protected default branch. +4. Trial the lane with a disposable pull request. Record time from update to checks, approval, + queue entry, and production deployment before expanding its allowlist. + +This process changes package policy, not the repository's underlying protection model. A package +can start with fast feedback and a narrow allowlist, then tighten or relax individual dials using +evidence from its own delivery times and failures. diff --git a/docs/architecture/website-delivery-validation.md b/docs/architecture/website-delivery-validation.md new file mode 100644 index 00000000000..c8d4f3925a0 --- /dev/null +++ b/docs/architecture/website-delivery-validation.md @@ -0,0 +1,41 @@ +# Website delivery validation + +The website trial answers one practical question: can a non-technical owner ship a website-only +change on their timeline while the rest of the monorepo keeps its current safeguards? + +## Current lane + +The `website` entry in `tools/cicd/fast-lane/src/lanes.ts` is the policy. It allows changes only +under `apps/website/`. `bertfy` is a trusted author. For other authors, a listed operator adds +`website-fast-lane:approve` to the current head; removing it withdraws the approval. +`website-fast-lane:hold`, a draft, a human change request, a fork, or a mixed-path change stops the +lane. A hold does not undo a merge that already happened. To resume after a hold, remove +`website-fast-lane:hold`; for an author who is not in the allowlist, also remove and re-apply +`website-fast-lane:approve`. If the run for an approval label shows as cancelled, a listed operator +re-runs it or re-applies the label; a re-run works only while the head is unchanged. + +The `website-approval` environment supplies `WEBSITE_APPROVAL_TOKEN`. The credential currently +belongs to `christian-byrne`, whose team membership satisfies the website path review rule. The +workflow verifies that identity before it acts and cannot approve Christian's own pull requests. +After approval it uses squash auto-merge or enters an already-clean exact head in GitHub's native +queue without queue jumping. Each `CI: Tests E2E` or `CI: Website E2E` completion re-runs the lane +for its pull request in case native auto-merge did not hand the head to the queue. + +Website-only pull requests run the normal required checks; the core unit and browser suites already +skip when nothing outside `apps/` changed. CodeRabbit is excluded from `apps/website/**` for this +trial; human change requests still block the lane. + +## Production identity and rollback + +Each production deploy records a `website-production` GitHub deployment for its commit, with the +immutable Vercel URL. To roll back, use Vercel's Instant Rollback on the last good production +deployment (dashboard or `vercel rollback `). Vercel then stops assigning new production +deployments, so once the fix has merged, use Undo Rollback (or `vercel promote `) on it. + +## Evidence to record + +Record timestamps for the contributor update, required checks, policy approval, queue entry, merge, +and production deployment. Also record any manual intervention, confusing UI, false-positive +check, or rollback problem. The trial succeeds only if the contributor can follow the path without +developer rescue and production can be tied to the expected commit. The allowlist should not expand +until the canary and rollback evidence are complete. diff --git a/knip.config.ts b/knip.config.ts index 1a983194b6f..0258bd889d7 100644 --- a/knip.config.ts +++ b/knip.config.ts @@ -58,6 +58,9 @@ const config: KnipConfig = { // Executed by models-snippets.test.ts inside the generated Node examples. ignoreDependencies: ['mime-types'] }, + 'tools/cicd/fast-lane': { + project: ['src/**/*.ts'] + }, 'tools/architecture': { project: ['src/**/*.ts'] }, diff --git a/package.json b/package.json index 856d0f65a6f..55061060a89 100644 --- a/package.json +++ b/package.json @@ -34,8 +34,8 @@ "dev": "vite --config vite.config.mts", "fallow": "fallow", "fallow:audit": "fallow audit", - "format:check": "oxfmt --check \"!apps/**\" \"!packages/**\" \"!tools/test-recorder/**\" \"!tools/architecture/**\"", - "format": "oxfmt --write \"!apps/**\" \"!packages/**\" \"!tools/test-recorder/**\" \"!tools/architecture/**\"", + "format:check": "oxfmt --check \"!apps/**\" \"!packages/**\" \"!tools/test-recorder/**\" \"!tools/architecture/**\" \"!tools/cicd/fast-lane/**\"", + "format": "oxfmt --write \"!apps/**\" \"!packages/**\" \"!tools/test-recorder/**\" \"!tools/architecture/**\" \"!tools/cicd/fast-lane/**\"", "json-schema": "tsx scripts/generate-json-schema.ts", "qa:desktop-frontend": "tsx scripts/qa-desktop-frontend.ts", "deps:audit": "depcruise src", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 1d3de45d76f..8e43ec28ed2 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1494,6 +1494,15 @@ importers: specifier: 'catalog:' version: 5.0.2(@types/node@25.9.5)(@vitest/coverage-v8@5.0.2)(@vitest/ui@5.0.2)(happy-dom@20.14.5)(jsdom@29.1.1)(vite@8.2.2(@types/node@25.9.5)(esbuild@0.28.1)(jiti@2.7.0)(terser@5.49.0)(tsx@4.23.1)(yaml@2.9.0)) + tools/cicd/fast-lane: + devDependencies: + '@types/node': + specifier: 'catalog:' + version: 25.9.5 + vitest: + specifier: 'catalog:' + version: 5.0.2(@types/node@25.9.5)(@vitest/coverage-v8@5.0.2)(@vitest/ui@5.0.2)(happy-dom@20.14.5)(jsdom@29.1.1)(vite@8.2.2(@types/node@25.9.5)(esbuild@0.28.1)(jiti@2.7.0)(terser@5.49.0)(tsx@4.23.1)(yaml@2.9.0)) + tools/test-recorder: dependencies: '@clack/prompts': diff --git a/scripts/server-fact-gate.test.ts b/scripts/server-fact-gate.test.ts index 1172823f0c7..a98840304ed 100644 --- a/scripts/server-fact-gate.test.ts +++ b/scripts/server-fact-gate.test.ts @@ -197,6 +197,7 @@ describe('server-fact gate on a real diff', () => { for (const linked of ['node_modules', 'tools']) { symlinkSync(path.join(repoRoot, linked), path.join(dir, linked)) } + mkdirSync(path.join(dir, '.git/info'), { recursive: true }) writeFileSync(path.join(dir, '.git/info/exclude'), 'node_modules\ntools\n') mkdirSync(path.join(dir, 'src')) writeFileSync(path.join(dir, gatedFile), before.join('\n')) @@ -216,6 +217,51 @@ describe('server-fact gate on a real diff', () => { ) } + function runStagedGateDuringMerge() { + const dir = mkdtempSync(path.join(tmpdir(), 'server-fact-gate-')) + workDir = dir + const run = (...args: string[]) => + execFileSync('git', args, { cwd: dir, stdio: 'ignore' }) + run('init', '-q') + run('config', 'user.email', 'gate@test.invalid') + run('config', 'user.name', 'gate') + for (const linked of ['node_modules', 'tools']) { + symlinkSync(path.join(repoRoot, linked), path.join(dir, linked)) + } + mkdirSync(path.join(dir, '.git/info'), { recursive: true }) + writeFileSync(path.join(dir, '.git/info/exclude'), 'node_modules\ntools\n') + mkdirSync(path.join(dir, 'src')) + writeFileSync(path.join(dir, gatedFile), 'export const ready = true\n') + run('add', '.') + run('commit', '-q', '-m', 'base') + run('branch', 'feature') + writeFileSync( + path.join(dir, gatedFile), + 'const { canInviteMembers } = useBillingCapabilities()\n' + + 'export const canInvite = canInviteMembers.value || isPlanEnded.value\n' + ) + run('add', gatedFile) + run('commit', '-q', '-m', 'upstream finding') + run('switch', '-q', 'feature') + writeFileSync( + path.join(dir, 'src/feature.ts'), + 'export const feature = true\n' + ) + run('add', 'src/feature.ts') + run('commit', '-q', '-m', 'feature') + run('merge', '--no-commit', '--no-ff', 'master') + return spawnSync( + process.execPath, + [ + '--import', + 'tsx', + path.join(repoRoot, 'scripts/server-fact-gate.ts'), + '--staged' + ], + { cwd: dir, encoding: 'utf8' } + ) + } + it('reports a recombination exposed by deleting only its pendingServerFact wrapper lines', () => { const wrapped = [ 'const { canInviteMembers } = useBillingCapabilities()', @@ -253,4 +299,12 @@ describe('server-fact gate on a real diff', () => { expect(result.stderr).toBe('') expect(result.status).toBe(0) }) + + it('checks the feature delta instead of upstream files during a merge', () => { + const result = runStagedGateDuringMerge() + + expect(result.stderr).toBe('') + expect(result.stdout).toContain('no findings on changed lines') + expect(result.status).toBe(0) + }) }) diff --git a/scripts/server-fact-gate.ts b/scripts/server-fact-gate.ts index e0bdaa04f33..ad6d9b8315e 100644 --- a/scripts/server-fact-gate.ts +++ b/scripts/server-fact-gate.ts @@ -15,8 +15,16 @@ function git(args: string[]): string { }) } +function stagedDiffArgs(): string[] { + try { + return ['--cached', git(['rev-parse', '--verify', 'MERGE_HEAD']).trim()] + } catch { + return ['--cached'] + } +} + function diffArgs(argv: string[]): string[] { - if (argv.includes('--staged')) return ['--cached'] + if (argv.includes('--staged')) return stagedDiffArgs() const baseIndex = argv.indexOf('--base') const base = baseIndex === -1 ? undefined : argv.at(baseIndex + 1) if (base === undefined) { diff --git a/tools/cicd/fast-lane/package.json b/tools/cicd/fast-lane/package.json new file mode 100644 index 00000000000..57dea3cb276 --- /dev/null +++ b/tools/cicd/fast-lane/package.json @@ -0,0 +1,15 @@ +{ + "name": "@comfyorg/fast-lane", + "version": "0.1.0", + "private": true, + "description": "Path-scoped policy approval and merge automation for package delivery lanes", + "type": "module", + "scripts": { + "format": "oxfmt --write", + "format:check": "oxfmt --check" + }, + "devDependencies": { + "@types/node": "catalog:", + "vitest": "catalog:" + } +} diff --git a/tools/cicd/fast-lane/src/__fixtures__/lane.ts b/tools/cicd/fast-lane/src/__fixtures__/lane.ts new file mode 100644 index 00000000000..eebe549c2e9 --- /dev/null +++ b/tools/cicd/fast-lane/src/__fixtures__/lane.ts @@ -0,0 +1,61 @@ +import { POLICY_REVIEW_PREFIX } from '../policy.ts' +import type { + FastLaneConfig, + PullRequest, + PullRequestReview +} from '../types.ts' + +export const repository = 'Comfy-Org/ComfyUI_frontend' +export const headSha = '0123456789abcdef0123456789abcdef01234567' +export const floorTime = '2026-10-06T10:00:00Z' + +export const lane: FastLaneConfig = { + id: 'website', + pathPrefixes: ['apps/website/'], + approval: { + identity: 'christian-byrne', + trustedAuthors: ['bertfy'], + approvalLabel: 'website-fast-lane:approve', + trustedLabelers: ['drjkl'], + holdLabel: 'website-fast-lane:hold' + } +} + +export const operatorLabelEvent = { + actor: 'drjkl', + label: 'website-fast-lane:approve' +} + +export function pullRequest(overrides: Partial = {}): PullRequest { + return { + state: 'open', + draft: false, + node_id: 'PR_1', + changed_files: 1, + user: { login: 'bertfy' }, + labels: [], + head: { sha: headSha, repo: { full_name: repository } }, + base: { ref: 'main', repo: { full_name: repository } }, + ...overrides + } +} + +export function outsider(labels: string[]): Partial { + return { + user: { login: 'someone-else' }, + labels: labels.map((name) => ({ name })) + } +} + +export function policyApproval( + overrides: Partial = {} +): PullRequestReview { + return { + state: 'APPROVED', + commit_id: headSha, + body: `${POLICY_REVIEW_PREFIX} Lane: website.`, + submitted_at: floorTime, + user: { login: 'christian-byrne' }, + ...overrides + } +} diff --git a/tools/cicd/fast-lane/src/automation.test.ts b/tools/cicd/fast-lane/src/automation.test.ts new file mode 100644 index 00000000000..897458526b3 --- /dev/null +++ b/tools/cicd/fast-lane/src/automation.test.ts @@ -0,0 +1,389 @@ +import { describe, expect, it, vi } from 'vitest' + +import { + floorTime, + headSha, + lane, + operatorLabelEvent, + outsider, + policyApproval, + pullRequest, + repository +} from './__fixtures__/lane.ts' +import { runFastLane, stopMergeAutomation } from './automation.ts' +import type { + GitHubClient, + MergeAutomationState, + PullRequest, + PullRequestFile, + PullRequestReview, + RuntimeConfig +} from './types.ts' + +const afterFloor = '2026-10-06T10:01:00Z' +const beforeFloor = '2026-10-06T09:59:00Z' + +type Write = [operation: string, payload: unknown] + +interface FakeOptions { + viewer?: string + pull?: Partial + reviews?: PullRequestReview[] + files?: PullRequestFile[] + mergeState?: Omit + failingMutations?: string[] + failDismissals?: boolean +} + +function runtimeConfig(overrides: Partial = {}): RuntimeConfig { + return { + repository, + pullRequestNumber: 42, + eventHeadSha: headSha, + defaultBranch: 'main', + lane, + ...overrides + } +} + +function fakeGitHub(options: FakeOptions = {}) { + const writes: Write[] = [] + const pull = pullRequest({ + changed_files: options.files?.length ?? 1, + ...options.pull + }) + const reviews = [...(options.reviews ?? [])] + const files = options.files ?? [ + { filename: 'apps/website/src/pages/index.astro' } + ] + + const github: GitHubClient = { + async request(path, init = {}) { + if (path === 'https://api.github.com/user') { + return { login: options.viewer ?? 'christian-byrne' } + } + if (init.method === 'POST') { + const body: PullRequestReview = JSON.parse(String(init.body)) + writes.push([`POST ${path}`, body]) + const created = policyApproval({ + id: 900, + commit_id: body.commit_id, + submitted_at: afterFloor, + body: body.body + }) + reviews.push(created) + return created + } + if (init.method === 'PUT') { + writes.push([`PUT ${path}`, JSON.parse(String(init.body))]) + if (options.failDismissals) throw new Error('dismissal rejected') + return null + } + return pull + }, + async paginate(path) { + return path.endsWith('/files') ? files : reviews + }, + async graphql(query, variables) { + const operation = /(?:query|mutation) (\w+)/.exec(query)?.[1] ?? '' + if (operation === 'PackageFastLaneMergeState') { + return { + node: { + id: 'PR_1', + headRefOid: pull.head?.sha, + ...options.mergeState + } + } + } + writes.push([operation, variables]) + if (options.failingMutations?.includes(operation)) { + throw new Error(`${operation} failed`) + } + return {} + } + } + return { github, writes } +} + +const approvalPost: Write = [ + 'POST /pulls/42/reviews', + expect.objectContaining({ event: 'APPROVE', commit_id: headSha }) +] +const enableAutoMerge: Write = [ + 'PackageFastLaneEnableAutoMerge', + { pullRequestId: 'PR_1', expectedHeadOid: headSha, mergeMethod: 'SQUASH' } +] +const disableAutoMerge: Write = [ + 'PackageFastLaneDisableAutoMerge', + { pullRequestId: 'PR_1' } +] +const dequeue: Write = ['PackageFastLaneDequeue', { pullRequestId: 'PR_1' }] + +function dismissal(id: number): Write { + return [ + `PUT /pulls/42/reviews/${id}/dismissals`, + { message: expect.stringContaining('Fast-lane approval withdrawn') } + ] +} + +const armedByLane = { + autoMergeRequest: { + enabledAt: afterFloor, + enabledBy: { login: 'christian-byrne' } + } +} + +describe('runFastLane', () => { + it.for([ + { + name: 'a trusted author', + options: {}, + config: {}, + writes: [approvalPost, enableAutoMerge] + }, + { + name: 'a non-allowlisted author on the operator label event', + options: { pull: outsider(['website-fast-lane:approve']) }, + config: { labelEvent: operatorLabelEvent }, + writes: [approvalPost, enableAutoMerge] + }, + { + name: 'a head that already has the policy approval', + options: { reviews: [policyApproval({ id: 1 })] }, + config: {}, + writes: [enableAutoMerge] + }, + { + name: 'a clean head', + options: { mergeState: { mergeStateStatus: 'CLEAN' } }, + config: {}, + writes: [ + approvalPost, + [ + 'PackageFastLaneEnqueue', + { pullRequestId: 'PR_1', expectedHeadOid: headSha } + ] + ] + }, + { + name: 'a head that advanced before arming', + options: { mergeState: { headRefOid: 'f'.repeat(40) } }, + config: {}, + writes: [approvalPost] + } + ] satisfies { + name: string + options: FakeOptions + config: Partial + writes: Write[] + }[])('approves and arms $name', async ({ options, config, writes }) => { + const fake = fakeGitHub(options) + + await runFastLane(fake.github, runtimeConfig(config), vi.fn()) + + expect(fake.writes).toEqual(writes) + }) + + it.for([ + { + name: 'a mixed-path change', + options: { + files: [ + { filename: 'apps/website/src/pages/index.astro' }, + { filename: 'src/main.ts' } + ] + } + }, + { + name: 'a truncated changed-file list', + options: { pull: { changed_files: 2 } } + }, + { + name: 'an active human change request', + options: { + reviews: [ + { state: 'CHANGES_REQUESTED', user: { login: 'DrJKL', type: 'User' } } + ] + } + }, + { + name: 'a pull request authored by the approval identity', + options: { pull: { user: { login: 'christian-byrne' } } } + }, + { + name: 'a non-allowlisted author whose labeled run was replaced', + options: { pull: outsider(['website-fast-lane:approve']) } + }, + { + name: 'a run for a head that has since advanced', + options: { + pull: { head: { sha: 'f'.repeat(40) } }, + reviews: [policyApproval({ id: 1, commit_id: 'f'.repeat(40) })], + mergeState: armedByLane + } + } + ] satisfies { name: string; options: FakeOptions }[])( + 'writes nothing for $name', + async ({ options }) => { + const fake = fakeGitHub(options) + + await runFastLane(fake.github, runtimeConfig(), vi.fn()) + + expect(fake.writes).toEqual([]) + } + ) + + it('withdraws approval and merge state when the approval label is removed', async () => { + const fake = fakeGitHub({ + pull: outsider([]), + reviews: [policyApproval({ id: 1 })], + mergeState: armedByLane + }) + + await runFastLane(fake.github, runtimeConfig(), vi.fn()) + + expect(fake.writes).toEqual([disableAutoMerge, dismissal(1)]) + }) + + it('rejects a token that belongs to another account before writing', async () => { + const fake = fakeGitHub({ viewer: 'someone-else' }) + + await expect( + runFastLane(fake.github, runtimeConfig(), vi.fn()) + ).rejects.toThrow('FAST_LANE_TOKEN belongs to someone-else') + expect(fake.writes).toEqual([]) + }) + + it('withdraws every policy approval on hold even when merge teardown fails', async () => { + const fake = fakeGitHub({ + pull: { labels: [{ name: 'website-fast-lane:hold' }] }, + reviews: [ + policyApproval({ id: 122, commit_id: 'old-head' }), + policyApproval({ id: 123 }) + ], + mergeState: armedByLane, + failingMutations: ['PackageFastLaneDisableAutoMerge'] + }) + const summary = vi.fn() + + await expect( + runFastLane(fake.github, runtimeConfig(), summary) + ).rejects.toThrow('failed to complete fast-lane compensation') + expect(fake.writes).toEqual([ + disableAutoMerge, + dismissal(122), + dismissal(123) + ]) + expect(summary).not.toHaveBeenCalled() + }) + + it('withdraws its approval once when arming fails', async () => { + const fake = fakeGitHub({ + failingMutations: ['PackageFastLaneEnableAutoMerge'] + }) + + await expect( + runFastLane(fake.github, runtimeConfig(), vi.fn()) + ).rejects.toThrow('PackageFastLaneEnableAutoMerge failed') + expect(fake.writes).toEqual([approvalPost, enableAutoMerge, dismissal(900)]) + }) +}) + +describe('stopMergeAutomation', () => { + it.for([ + { + name: 'queue entry and auto-merge created by the lane after its floor', + mergeState: { + ...armedByLane, + mergeQueueEntry: { + id: 'MQE_1', + enqueuedAt: afterFloor, + enqueuer: { login: 'christian-byrne' } + } + }, + writes: [dequeue, disableAutoMerge] + }, + { + name: 'a queue entry by another account', + mergeState: { + ...armedByLane, + mergeQueueEntry: { + id: 'MQE_1', + enqueuedAt: afterFloor, + enqueuer: { login: 'drjkl' } + } + }, + writes: [disableAutoMerge] + }, + { + name: 'a queue entry from before the floor', + mergeState: { + mergeQueueEntry: { + id: 'MQE_1', + enqueuedAt: beforeFloor, + enqueuer: { login: 'christian-byrne' } + } + }, + writes: [] + }, + { + name: 'auto-merge enabled by another account', + mergeState: { + autoMergeRequest: { + enabledAt: afterFloor, + enabledBy: { login: 'drjkl' } + } + }, + writes: [] + }, + { + name: 'auto-merge enabled before the floor', + mergeState: { + autoMergeRequest: { + enabledAt: beforeFloor, + enabledBy: { login: 'christian-byrne' } + } + }, + writes: [] + } + ] satisfies { + name: string + mergeState: Omit + writes: Write[] + }[])( + 'withdraws only lane-owned state for $name', + async ({ mergeState, writes }) => { + const fake = fakeGitHub({ mergeState }) + + await stopMergeAutomation( + fake.github, + { node_id: 'PR_1' }, + 'christian-byrne', + { submitted_at: floorTime } + ) + + expect(fake.writes).toEqual(writes) + } + ) + + it('still disables auto-merge when dequeue fails', async () => { + const fake = fakeGitHub({ + mergeState: { + ...armedByLane, + mergeQueueEntry: { + id: 'MQE_1', + enqueuedAt: afterFloor, + enqueuer: { login: 'christian-byrne' } + } + }, + failingMutations: ['PackageFastLaneDequeue'] + }) + + await expect( + stopMergeAutomation(fake.github, { node_id: 'PR_1' }, 'christian-byrne', { + submitted_at: floorTime + }) + ).rejects.toThrow('failed to stop all merge automation') + expect(fake.writes).toEqual([dequeue, disableAutoMerge]) + }) +}) diff --git a/tools/cicd/fast-lane/src/automation.ts b/tools/cicd/fast-lane/src/automation.ts new file mode 100644 index 00000000000..49329d61271 --- /dev/null +++ b/tools/cicd/fast-lane/src/automation.ts @@ -0,0 +1,377 @@ +import { isRecord } from './github.ts' +import { + activePolicyApprovals, + eligibilityFailure, + isLogin, + isPolicyApprovalForHead, + pathFailure, + policyReviewFloor, + POLICY_REVIEW_PREFIX +} from './policy.ts' +import type { + GitHubClient, + MergeAutomationState, + PullRequest, + PullRequestFile, + PullRequestReview, + RuntimeConfig, + SubmittedReview, + Summary +} from './types.ts' + +interface PullState { + pull: PullRequest + reviews: PullRequestReview[] +} + +const MERGE_AUTOMATION_STATE = ` + query PackageFastLaneMergeState($pullRequestId: ID!) { + node(id: $pullRequestId) { + ... on PullRequest { + id + headRefOid + mergeStateStatus + autoMergeRequest { enabledAt enabledBy { login } } + mergeQueueEntry { + id + enqueuedAt + enqueuer { login } + headCommit { oid } + } + } + } + } +` + +function shortSha(sha: string): string { + return sha.slice(0, 12) +} + +function asPullRequest(value: unknown): PullRequest { + if (!isRecord(value)) throw new Error('GitHub did not return a pull request') + return value +} + +function mergeState(value: unknown): MergeAutomationState { + const node = isRecord(value) + ? (value as { node?: MergeAutomationState }).node + : undefined + if (!node?.id) { + throw new Error('GitHub did not return the pull request merge state') + } + return node +} + +function atOrAfter(value: string | undefined, floor: string): boolean { + if (!value) return false + return Date.parse(value) >= Date.parse(floor) +} + +async function readMergeState( + github: GitHubClient, + pull: PullRequest +): Promise { + if (!pull.node_id) throw new Error('the pull request node id is required') + return mergeState( + await github.graphql(MERGE_AUTOMATION_STATE, { + pullRequestId: pull.node_id + }) + ) +} + +async function attemptAll( + tasks: (() => Promise)[], + message: string +): Promise { + const errors: unknown[] = [] + for (const task of tasks) { + try { + await task() + } catch (error) { + errors.push(error) + } + } + if (errors.length > 0) throw new AggregateError(errors, message) +} + +export async function stopMergeAutomation( + github: GitHubClient, + pull: PullRequest, + identity: string, + floor: SubmittedReview | undefined +): Promise { + if (!floor) return + const { id, mergeQueueEntry, autoMergeRequest } = await readMergeState( + github, + pull + ) + const ownedSinceFloor = ( + actor: { login?: string } | undefined, + at: string | undefined + ) => isLogin(actor, identity) && atOrAfter(at, floor.submitted_at) + + const dequeue = () => + github.graphql( + `mutation PackageFastLaneDequeue($pullRequestId: ID!) { + dequeuePullRequest(input: { id: $pullRequestId }) { clientMutationId } + }`, + { pullRequestId: id } + ) + const disableAutoMerge = () => + github.graphql( + `mutation PackageFastLaneDisableAutoMerge($pullRequestId: ID!) { + disablePullRequestAutoMerge(input: { pullRequestId: $pullRequestId }) { + clientMutationId + } + }`, + { pullRequestId: id } + ) + + await attemptAll( + [ + ...(mergeQueueEntry?.id && + ownedSinceFloor(mergeQueueEntry.enqueuer, mergeQueueEntry.enqueuedAt) + ? [dequeue] + : []), + ...(autoMergeRequest && + ownedSinceFloor(autoMergeRequest.enabledBy, autoMergeRequest.enabledAt) + ? [disableAutoMerge] + : []) + ], + 'failed to stop all merge automation' + ) +} + +async function armMergeAutomation( + github: GitHubClient, + pull: PullRequest, + config: RuntimeConfig, + summary: Summary +): Promise { + const headSha = config.eventHeadSha + const state = await readMergeState(github, pull) + if (state.headRefOid !== headSha) { + summary('Skipped: the pull request head advanced before merge automation.') + return + } + if (state.mergeQueueEntry) { + summary(`Already queued ${shortSha(headSha)}.`) + return + } + if (state.mergeStateStatus === 'CLEAN') { + await github.graphql( + `mutation PackageFastLaneEnqueue( + $pullRequestId: ID! + $expectedHeadOid: GitObjectID! + ) { + enqueuePullRequest(input: { + pullRequestId: $pullRequestId + expectedHeadOid: $expectedHeadOid + jump: false + }) { clientMutationId } + }`, + { pullRequestId: state.id, expectedHeadOid: headSha } + ) + summary(`Entered the native merge queue for ${shortSha(headSha)}.`) + return + } + if (state.autoMergeRequest) { + summary(`Auto-merge already armed for ${shortSha(headSha)}.`) + return + } + + await github.graphql( + `mutation PackageFastLaneEnableAutoMerge( + $pullRequestId: ID! + $expectedHeadOid: GitObjectID! + $mergeMethod: PullRequestMergeMethod! + ) { + enablePullRequestAutoMerge(input: { + pullRequestId: $pullRequestId + expectedHeadOid: $expectedHeadOid + mergeMethod: $mergeMethod + }) { clientMutationId } + }`, + { + pullRequestId: state.id, + expectedHeadOid: headSha, + mergeMethod: 'SQUASH' + } + ) + summary(`Armed native auto-merge for ${shortSha(headSha)}.`) +} + +async function dismissApproval( + github: GitHubClient, + pullRequestNumber: number, + review: PullRequestReview, + reason: string +): Promise { + if (!review.id) return + await github.request( + `/pulls/${pullRequestNumber}/reviews/${review.id}/dismissals`, + { + method: 'PUT', + headers: { 'content-type': 'application/json' }, + body: JSON.stringify({ + message: `Fast-lane approval withdrawn: ${reason}` + }) + } + ) +} + +async function withdraw( + github: GitHubClient, + config: RuntimeConfig, + { pull, reviews }: PullState, + reason: string, + summary: Summary +): Promise { + const identity = config.lane.approval.identity + await attemptAll( + [ + () => + stopMergeAutomation( + github, + pull, + identity, + policyReviewFloor(reviews, identity) + ), + ...activePolicyApprovals(reviews, identity).map( + (approval) => () => + dismissApproval(github, config.pullRequestNumber, approval, reason) + ) + ], + 'failed to complete fast-lane compensation' + ) + summary(`Skipped: ${reason}`) +} + +async function readPullState( + github: GitHubClient, + pullRequestNumber: number +): Promise { + const [pull, reviews] = await Promise.all([ + github.request(`/pulls/${pullRequestNumber}`), + github.paginate(`/pulls/${pullRequestNumber}/reviews`) + ]) + return { + pull: asPullRequest(pull), + reviews: reviews as PullRequestReview[] + } +} + +async function revalidateOrWithdraw( + github: GitHubClient, + config: RuntimeConfig, + summary: Summary +): Promise { + const state = await readPullState(github, config.pullRequestNumber) + if (state.pull.head?.sha !== config.eventHeadSha) { + summary('Skipped: the pull request head advanced after this run started.') + return + } + const reason = eligibilityFailure({ + pull: state.pull, + reviews: state.reviews, + lane: config.lane, + repository: config.repository, + defaultBranch: config.defaultBranch, + labelEvent: config.labelEvent + }) + if (!reason) return state + await withdraw(github, config, state, reason, summary) +} + +async function assertIdentity( + github: GitHubClient, + expectedIdentity: string +): Promise { + const response = await github.request('https://api.github.com/user') + const login = + isRecord(response) && typeof response.login === 'string' + ? response.login + : undefined + if (!isLogin({ login }, expectedIdentity)) { + throw new Error( + `FAST_LANE_TOKEN belongs to ${login ?? 'an unknown account'}, expected ${expectedIdentity}` + ) + } +} + +async function postPolicyApproval( + github: GitHubClient, + config: RuntimeConfig +): Promise { + await github.request(`/pulls/${config.pullRequestNumber}/reviews`, { + method: 'POST', + headers: { 'content-type': 'application/json' }, + body: JSON.stringify({ + event: 'APPROVE', + commit_id: config.eventHeadSha, + body: `${POLICY_REVIEW_PREFIX} Lane: ${config.lane.id}. No diff review was performed; eligibility was bound to the trusted policy, exact head, and configured path boundary.` + }) + }) +} + +async function withdrawAfterFailure( + github: GitHubClient, + config: RuntimeConfig, + error: unknown, + summary: Summary +): Promise { + try { + const current = await readPullState(github, config.pullRequestNumber) + await withdraw( + github, + config, + current, + 'the run failed after approval; approval and merge state were withdrawn.', + summary + ) + } catch (cleanupError) { + throw new Error( + `Fast-lane run failed (${String(error)}) and compensation also failed.`, + { cause: cleanupError } + ) + } + throw error +} + +export async function runFastLane( + github: GitHubClient, + config: RuntimeConfig, + summary: Summary +): Promise { + const { identity } = config.lane.approval + const headSha = config.eventHeadSha + await assertIdentity(github, identity) + const initial = await revalidateOrWithdraw(github, config, summary) + if (!initial) return + + const files = (await github.paginate( + `/pulls/${config.pullRequestNumber}/files` + )) as PullRequestFile[] + const outsideLane = pathFailure(files, initial.pull, config.lane.pathPrefixes) + if (outsideLane) { + await withdraw(github, config, initial, outsideLane, summary) + return + } + + const alreadyApproved = initial.reviews.some((review) => + isPolicyApprovalForHead(review, identity, headSha) + ) + if (!alreadyApproved) await postPolicyApproval(github, config) + + try { + const verified = await revalidateOrWithdraw(github, config, summary) + if (!verified) return + summary( + `${alreadyApproved ? 'Already approved' : 'Approved'} ${shortSha(headSha)} as @${identity}.` + ) + await armMergeAutomation(github, verified.pull, config, summary) + await revalidateOrWithdraw(github, config, summary) + } catch (error) { + await withdrawAfterFailure(github, config, error, summary) + } +} diff --git a/tools/cicd/fast-lane/src/config.test.ts b/tools/cicd/fast-lane/src/config.test.ts new file mode 100644 index 00000000000..6ea4213f1d1 --- /dev/null +++ b/tools/cicd/fast-lane/src/config.test.ts @@ -0,0 +1,65 @@ +import { beforeEach, describe, expect, it, vi } from 'vitest' + +import { operatorLabelEvent } from './__fixtures__/lane.ts' +import { loadRuntimeConfig } from './config.ts' +import { lanes } from './lanes.ts' + +it.for(lanes)('keeps the $id lane in the form the engine compares', (lane) => { + for (const value of Object.values(lane.approval).flat()) { + expect(value).toBe(value.toLowerCase()) + } + for (const prefix of lane.pathPrefixes) { + expect(prefix).toMatch(/\/$/) + expect(prefix).not.toMatch(/^\/|(^|\/)\.\.\//) + } +}) + +describe('runtime configuration', () => { + beforeEach(() => { + vi.stubEnv('FAST_LANE', 'website') + vi.stubEnv('GITHUB_REPOSITORY', 'Comfy-Org/ComfyUI_frontend') + vi.stubEnv('PR_NUMBER', '42') + vi.stubEnv('PR_HEAD_SHA', 'head-sha') + vi.stubEnv('FAST_LANE_DEFAULT_BRANCH', 'main') + }) + + it.for([ + { + name: 'an operator label event', + eventName: 'pull_request_target', + action: 'labeled', + expected: operatorLabelEvent + }, + { + name: 'an unlabeled event', + eventName: 'pull_request_target', + action: 'unlabeled', + expected: undefined + }, + { + name: 'a check completion', + eventName: 'workflow_run', + action: 'labeled', + expected: undefined + } + ])( + 'reads $name as label event $expected', + ({ eventName, action, expected }) => { + vi.stubEnv('GITHUB_EVENT_NAME', eventName) + vi.stubEnv('FAST_LANE_EVENT_ACTION', action) + vi.stubEnv('FAST_LANE_EVENT_ACTOR', 'DrJKL') + vi.stubEnv('FAST_LANE_EVENT_LABEL', 'Website-Fast-Lane:Approve') + expect(loadRuntimeConfig().labelEvent).toEqual(expected) + } + ) + + it('rejects an unconfigured lane', () => { + vi.stubEnv('FAST_LANE', 'docs') + expect(() => loadRuntimeConfig()).toThrow('not a configured lane') + }) + + it('requires the pull request number', () => { + vi.stubEnv('PR_NUMBER', '') + expect(() => loadRuntimeConfig()).toThrow('PR_NUMBER is required') + }) +}) diff --git a/tools/cicd/fast-lane/src/config.ts b/tools/cicd/fast-lane/src/config.ts new file mode 100644 index 00000000000..134eaa6a773 --- /dev/null +++ b/tools/cicd/fast-lane/src/config.ts @@ -0,0 +1,45 @@ +import { lanes } from './lanes.ts' +import type { LabelEvent, RuntimeConfig } from './types.ts' + +export function requiredEnv(name: string): string { + const value = process.env[name]?.trim() + if (!value) throw new Error(`${name} is required`) + return value +} + +function positiveIntegerEnv(name: string): number { + const parsed = Number(requiredEnv(name)) + if (!Number.isSafeInteger(parsed) || parsed <= 0) { + throw new Error(`${name} must be a positive integer`) + } + return parsed +} + +function labelEventEnv(): LabelEvent | undefined { + const actor = process.env.FAST_LANE_EVENT_ACTOR?.trim() + const label = process.env.FAST_LANE_EVENT_LABEL?.trim() + if ( + process.env.GITHUB_EVENT_NAME !== 'pull_request_target' || + process.env.FAST_LANE_EVENT_ACTION !== 'labeled' || + !actor || + !label + ) { + return + } + return { actor: actor.toLowerCase(), label: label.toLowerCase() } +} + +export function loadRuntimeConfig(): RuntimeConfig { + const laneId = requiredEnv('FAST_LANE') + const lane = lanes.find((candidate) => candidate.id === laneId) + if (!lane) throw new Error(`FAST_LANE ${laneId} is not a configured lane`) + + return { + repository: requiredEnv('GITHUB_REPOSITORY'), + pullRequestNumber: positiveIntegerEnv('PR_NUMBER'), + eventHeadSha: requiredEnv('PR_HEAD_SHA'), + labelEvent: labelEventEnv(), + defaultBranch: requiredEnv('FAST_LANE_DEFAULT_BRANCH'), + lane + } +} diff --git a/tools/cicd/fast-lane/src/github.test.ts b/tools/cicd/fast-lane/src/github.test.ts new file mode 100644 index 00000000000..2bab38db884 --- /dev/null +++ b/tools/cicd/fast-lane/src/github.test.ts @@ -0,0 +1,47 @@ +import { describe, expect, it, vi } from 'vitest' + +import { createGitHubClient } from './github.ts' + +function jsonResponse(body: unknown): Response { + return new Response(JSON.stringify(body), { + status: 200, + headers: { 'content-type': 'application/json' } + }) +} + +describe('GitHub client', () => { + it('rejects a GraphQL response that reports errors with HTTP 200', async () => { + vi.mocked(fetch).mockResolvedValueOnce( + jsonResponse({ + data: null, + errors: [{ message: 'Could not resolve to a node' }] + }) + ) + const github = createGitHubClient('token', 'Comfy-Org/ComfyUI_frontend') + + await expect(github.graphql('mutation {}', {})).rejects.toThrow( + 'GitHub GraphQL failed: Could not resolve to a node' + ) + }) + + it('reads every page until a short page', async () => { + const fullPage = Array.from({ length: 100 }, (_, id) => ({ id })) + vi.mocked(fetch).mockImplementation(async (input) => + jsonResponse(String(input).endsWith('page=1') ? fullPage : [{ id: 100 }]) + ) + const github = createGitHubClient('token', 'Comfy-Org/ComfyUI_frontend') + + await expect(github.paginate('/pulls/42/reviews')).resolves.toHaveLength( + 101 + ) + }) + + it('refuses to send the token to another origin', async () => { + const github = createGitHubClient('token', 'Comfy-Org/ComfyUI_frontend') + + await expect(github.request('https://example.com/user')).rejects.toThrow( + 'Refusing to send credentials' + ) + expect(fetch).not.toHaveBeenCalled() + }) +}) diff --git a/tools/cicd/fast-lane/src/github.ts b/tools/cicd/fast-lane/src/github.ts new file mode 100644 index 00000000000..b191705a0fb --- /dev/null +++ b/tools/cicd/fast-lane/src/github.ts @@ -0,0 +1,108 @@ +import type { GitHubClient } from './types.ts' + +const API_VERSION = '2022-11-28' +const PAGE_SIZE = 100 +const GRAPHQL_URL = 'https://api.github.com/graphql' + +export function isRecord(value: unknown): value is Record { + return typeof value === 'object' && value !== null && !Array.isArray(value) +} + +function apiUrl(root: string, requestPath: string): string { + if (!requestPath.startsWith('https://')) return `${root}${requestPath}` + if (new URL(requestPath).origin !== 'https://api.github.com') { + throw new Error(`Refusing to send credentials to ${requestPath}`) + } + return requestPath +} + +async function assertSuccessful( + response: Response, + method: string, + requestPath: string +): Promise { + if (response.ok) return + const body = (await response.text()).slice(0, 500) + throw new Error( + `GitHub API ${method} ${requestPath} failed: ${response.status} ${body}` + ) +} + +function arrayPage(value: unknown, requestPath: string): unknown[] { + if (Array.isArray(value)) return value + throw new Error(`GitHub API ${requestPath} did not return an array`) +} + +function graphqlData(value: unknown): unknown { + if (!isRecord(value)) { + throw new Error('GitHub GraphQL returned an invalid response') + } + const errors = Array.isArray(value.errors) ? value.errors : [] + if (errors.length === 0) return value.data + const messages = errors.map((error) => + isRecord(error) && typeof error.message === 'string' + ? error.message + : 'unknown error' + ) + throw new Error(`GitHub GraphQL failed: ${messages.join('; ')}`) +} + +export function createGitHubClient( + token: string, + repository: string +): GitHubClient { + const root = `https://api.github.com/repos/${repository}` + const headers = { + accept: 'application/vnd.github+json', + authorization: `Bearer ${token}`, + 'x-github-api-version': API_VERSION, + 'user-agent': 'comfy-package-fast-lane/1.0' + } + + async function request( + requestPath: string, + options: RequestInit = {} + ): Promise { + const requestHeaders = new Headers(headers) + new Headers(options.headers).forEach((value, name) => { + requestHeaders.set(name, value) + }) + const response = await fetch(apiUrl(root, requestPath), { + ...options, + headers: requestHeaders + }) + await assertSuccessful(response, options.method ?? 'GET', requestPath) + if (response.status === 204) return null + return response.json() + } + + async function paginate(requestPath: string): Promise { + const rows: unknown[] = [] + for (let page = 1; ; page += 1) { + const separator = requestPath.includes('?') ? '&' : '?' + const body = arrayPage( + await request( + `${requestPath}${separator}per_page=${PAGE_SIZE}&page=${page}` + ), + requestPath + ) + rows.push(...body) + if (body.length < PAGE_SIZE) return rows + } + } + + async function graphql( + query: string, + variables: Record + ): Promise { + return graphqlData( + await request(GRAPHQL_URL, { + method: 'POST', + headers: { 'content-type': 'application/json' }, + body: JSON.stringify({ query, variables }) + }) + ) + } + + return { request, paginate, graphql } +} diff --git a/tools/cicd/fast-lane/src/lanes.ts b/tools/cicd/fast-lane/src/lanes.ts new file mode 100644 index 00000000000..ad38e288551 --- /dev/null +++ b/tools/cicd/fast-lane/src/lanes.ts @@ -0,0 +1,15 @@ +import type { FastLaneConfig } from './types.ts' + +export const lanes: FastLaneConfig[] = [ + { + id: 'website', + pathPrefixes: ['apps/website/'], + approval: { + identity: 'christian-byrne', + trustedAuthors: ['bertfy'], + approvalLabel: 'website-fast-lane:approve', + trustedLabelers: ['christian-byrne', 'drjkl', 'benjcooley'], + holdLabel: 'website-fast-lane:hold' + } + } +] diff --git a/tools/cicd/fast-lane/src/policy.test.ts b/tools/cicd/fast-lane/src/policy.test.ts new file mode 100644 index 00000000000..b278ebb4144 --- /dev/null +++ b/tools/cicd/fast-lane/src/policy.test.ts @@ -0,0 +1,324 @@ +import { describe, expect, it } from 'vitest' + +import { + headSha, + lane, + operatorLabelEvent, + outsider, + policyApproval, + pullRequest, + repository +} from './__fixtures__/lane.ts' +import { + activePolicyApprovals, + changedPaths, + eligibilityFailure, + hasActiveHumanChangeRequest, + hasCompleteChangedFileList, + isAuthorizedLabelEvent, + isInsideLane, + isPolicyApprovalForHead, + policyReviewFloor +} from './policy.ts' +import type { LabelEvent, PullRequest, PullRequestReview } from './types.ts' + +const headApproval = policyApproval() + +function outsiderPull(labels: string[]): PullRequest { + return pullRequest(outsider(labels)) +} + +function failure( + pull: PullRequest, + { + reviews = [], + labelEvent + }: { reviews?: PullRequestReview[]; labelEvent?: LabelEvent } = {} +): string | undefined { + return eligibilityFailure({ + pull, + reviews, + lane, + repository, + defaultBranch: 'main', + labelEvent + }) +} + +describe('changed-path boundary', () => { + it.for([ + { name: 'a matching count', expectedCount: 1, expected: true }, + { name: 'a truncated list', expectedCount: 2, expected: false }, + { name: 'an unknown count', expectedCount: undefined, expected: false } + ])('treats $name as complete: $expected', ({ expectedCount, expected }) => { + expect( + hasCompleteChangedFileList( + [{ filename: 'apps/website/src/pages/index.astro' }], + expectedCount + ) + ).toBe(expected) + }) + + it.for([ + { + name: 'a lane path', + paths: ['apps/website/src/pages/index.astro'], + expected: true + }, + { name: 'no paths', paths: [], expected: false }, + { + name: 'a lane path and a root file', + paths: ['apps/website/src/pages/index.astro', 'pnpm-lock.yaml'], + expected: false + }, + { + name: 'a sibling directory sharing the prefix', + paths: ['apps/website-evil/file.ts'], + expected: false + } + ])('treats $name as inside the lane: $expected', ({ paths, expected }) => { + expect(isInsideLane(paths, lane.pathPrefixes)).toBe(expected) + }) + + it.for([ + { name: 'rename', status: 'renamed' }, + { name: 'copy', status: 'copied' } + ])('retains both paths for a $name into the lane', ({ status }) => { + expect( + changedPaths([ + { + status, + previous_filename: 'src/sensitive.ts', + filename: 'apps/website/sensitive.ts' + } + ]) + ).toEqual(['apps/website/sensitive.ts', 'src/sensitive.ts']) + }) + + it('fails closed when a rename omits its previous path', () => { + expect( + changedPaths([{ status: 'renamed', filename: 'apps/website/new.astro' }]) + ).toBeUndefined() + }) +}) + +describe('approval label events', () => { + it.for([ + { + name: 'the trusted operator label event', + event: operatorLabelEvent, + expected: true + }, + { + name: 'an untrusted labeler', + event: { ...operatorLabelEvent, actor: 'someone-else' }, + expected: false + }, + { + name: 'a different label from the operator', + event: { ...operatorLabelEvent, label: 'area:website' }, + expected: false + }, + { name: 'a run without a label event', event: undefined, expected: false } + ])('authorizes $name: $expected', ({ event, expected }) => { + expect(isAuthorizedLabelEvent(lane, event)).toBe(expected) + }) +}) + +describe('eligibility', () => { + it.for([ + { name: 'a trusted author', pull: pullRequest() }, + { + name: 'a non-allowlisted author on the operator label event', + pull: outsiderPull(['website-fast-lane:approve']), + labelEvent: operatorLabelEvent + }, + { + name: 'a non-allowlisted author whose head approval and label remain', + pull: outsiderPull(['website-fast-lane:approve']), + reviews: [headApproval] + } + ])('accepts $name', ({ pull, reviews, labelEvent }) => { + expect(failure(pull, { reviews, labelEvent })).toBeUndefined() + }) + + it.for([ + { + name: 'draft', + pull: pullRequest({ draft: true }), + message: 'not open and ready' + }, + { + name: 'closed pull request', + pull: pullRequest({ state: 'closed' }), + message: 'not open and ready' + }, + { + name: 'other base', + pull: pullRequest({ + base: { + ref: 'release', + repo: { full_name: repository } + } + }), + message: 'applies only to main' + }, + { + name: 'base in another repository', + pull: pullRequest({ + base: { ref: 'main', repo: { full_name: 'bertfy/ComfyUI_frontend' } } + }), + message: 'applies only to main' + }, + { + name: 'fork', + pull: pullRequest({ + head: { sha: headSha, repo: { full_name: 'bertfy/ComfyUI_frontend' } } + }), + message: 'fork pull requests' + }, + { + name: 'pull request authored by the approval identity', + pull: pullRequest({ user: { login: 'Christian-Byrne' } }), + message: 'cannot approve its own pull request' + }, + { + name: 'non-allowlisted author without the label', + pull: outsiderPull([]), + message: 'is not applied' + }, + { + name: 'non-allowlisted author whose label was removed after approval', + pull: outsiderPull([]), + reviews: [headApproval], + message: 'is not applied' + }, + { + name: 'non-allowlisted author with the label but no current event', + pull: outsiderPull(['website-fast-lane:approve']), + message: 'lacks a current authorized event' + }, + { + name: 'hold label', + pull: pullRequest({ labels: [{ name: 'website-fast-lane:hold' }] }), + message: 'hold is applied' + }, + { + name: 'human change request', + pull: pullRequest(), + reviews: [ + { state: 'CHANGES_REQUESTED', user: { login: 'DrJKL', type: 'User' } } + ], + message: 'active human change request' + } + ])('rejects $name', ({ pull, reviews, message }) => { + expect(failure(pull, { reviews })).toContain(message) + }) +}) + +describe('human change requests', () => { + it.for([ + { + name: 'a change request followed by a comment', + reviews: [ + { state: 'CHANGES_REQUESTED', user: { login: 'DrJKL', type: 'User' } }, + { state: 'COMMENTED', user: { login: 'DrJKL', type: 'User' } } + ], + expected: true + }, + { + name: 'an app change request and a later human approval', + reviews: [ + { + state: 'CHANGES_REQUESTED', + user: { login: 'coderabbitai[bot]', type: 'Bot' } + }, + { state: 'CHANGES_REQUESTED', user: { login: 'DrJKL', type: 'User' } }, + { state: 'APPROVED', user: { login: 'DrJKL', type: 'User' } } + ], + expected: false + }, + { + name: 'a change request that was dismissed', + reviews: [{ state: 'DISMISSED', user: { login: 'DrJKL', type: 'User' } }], + expected: false + } + ])('treats $name as active: $expected', ({ reviews, expected }) => { + expect(hasActiveHumanChangeRequest(reviews)).toBe(expected) + }) +}) + +describe('policy reviews', () => { + it.for([ + { + name: 'the identity on the head in any case', + review: { ...headApproval, user: { login: 'Christian-Byrne' } }, + expected: true + }, + { + name: 'an older head', + review: { ...headApproval, commit_id: 'old-sha' }, + expected: false + }, + { + name: 'another reviewer', + review: { ...headApproval, user: { login: 'drjkl' } }, + expected: false + }, + { + name: 'a dismissed approval of the head', + review: { ...headApproval, state: 'DISMISSED' }, + expected: false + }, + { + name: 'an unmarked approval by the identity', + review: { ...headApproval, body: 'Looks good to me' }, + expected: false + } + ])( + 'treats $name as the head policy approval: $expected', + ({ review, expected }) => { + expect(isPolicyApprovalForHead(review, 'christian-byrne', headSha)).toBe( + expected + ) + } + ) + + it('selects active policy approvals across heads', () => { + expect( + activePolicyApprovals( + [ + { ...headApproval, id: 1, commit_id: 'old-head' }, + { ...headApproval, id: 2 }, + { ...headApproval, id: 3, state: 'DISMISSED' }, + { ...headApproval, id: 4, body: 'Looks good to me' } + ], + 'christian-byrne' + ).map((review) => review.id) + ).toEqual([1, 2]) + }) + + it('uses the earliest policy review as the automation ownership floor', () => { + expect( + policyReviewFloor( + [ + { + ...headApproval, + submitted_at: '2026-10-06T10:03:00Z' + }, + { + ...headApproval, + state: 'DISMISSED', + submitted_at: '2026-10-06T10:00:00Z' + }, + { + ...headApproval, + body: 'Looks good to me.', + submitted_at: '2026-10-06T09:00:00Z' + } + ], + 'christian-byrne' + )?.submitted_at + ).toBe('2026-10-06T10:00:00Z') + }) +}) diff --git a/tools/cicd/fast-lane/src/policy.ts b/tools/cicd/fast-lane/src/policy.ts new file mode 100644 index 00000000000..020759aa29b --- /dev/null +++ b/tools/cicd/fast-lane/src/policy.ts @@ -0,0 +1,225 @@ +import type { + FastLaneConfig, + LabelEvent, + PullRequest, + PullRequestFile, + PullRequestReview, + RepositoryRef, + SubmittedReview +} from './types.ts' + +export const POLICY_REVIEW_PREFIX = '[Package fast lane] Policy-only approval.' + +const DECISIVE_REVIEW_STATES = new Set([ + 'APPROVED', + 'CHANGES_REQUESTED', + 'DISMISSED' +]) + +export interface EligibilityContext { + pull: PullRequest + reviews: PullRequestReview[] + lane: FastLaneConfig + repository: string + defaultBranch: string + labelEvent?: LabelEvent +} + +export function changedPaths(files: PullRequestFile[]): string[] | undefined { + const paths: string[] = [] + for (const file of files) { + if (typeof file.filename !== 'string') return + paths.push(file.filename) + + if (file.previous_filename === undefined) { + if (file.status === 'renamed' || file.status === 'copied') return + continue + } + if (typeof file.previous_filename !== 'string') return + paths.push(file.previous_filename) + } + return paths +} + +export function hasCompleteChangedFileList( + files: PullRequestFile[], + expectedCount: number | undefined +): boolean { + return Number.isSafeInteger(expectedCount) && files.length === expectedCount +} + +export function isInsideLane(paths: string[], prefixes: string[]): boolean { + return ( + paths.length > 0 && + paths.every((path) => prefixes.some((prefix) => path.startsWith(prefix))) + ) +} + +export function pathFailure( + files: PullRequestFile[], + pull: PullRequest, + prefixes: string[] +): string | undefined { + const paths = hasCompleteChangedFileList(files, pull.changed_files) + ? changedPaths(files) + : undefined + if (!paths || !isInsideLane(paths, prefixes)) { + return 'the complete changed-file set is not inside the configured lane.' + } +} + +function hasLabel(pull: PullRequest, expected: string): boolean { + return Boolean( + pull.labels?.some((label) => label.name?.toLowerCase() === expected) + ) +} + +export function isLogin( + user: { login?: string } | undefined, + login: string +): boolean { + return user?.login?.toLowerCase() === login +} + +export function isAuthorizedLabelEvent( + lane: FastLaneConfig, + labelEvent: LabelEvent | undefined +): boolean { + return ( + labelEvent?.label === lane.approval.approvalLabel && + lane.approval.trustedLabelers.includes(labelEvent.actor) + ) +} + +export function hasActiveHumanChangeRequest( + reviews: PullRequestReview[] +): boolean { + const latestState = new Map() + for (const review of reviews) { + const login = review.user?.login?.toLowerCase() + if ( + !login || + review.user?.type === 'Bot' || + login.endsWith('[bot]') || + !review.state || + !DECISIVE_REVIEW_STATES.has(review.state) + ) { + continue + } + latestState.set(login, review.state) + } + return [...latestState.values()].includes('CHANGES_REQUESTED') +} + +function isRepository( + repo: RepositoryRef | null | undefined, + repository: string +): boolean { + return repo?.full_name?.toLowerCase() === repository.toLowerCase() +} + +function isPolicyReview(review: PullRequestReview, identity: string): boolean { + return ( + isLogin(review.user, identity) && + review.body?.startsWith(POLICY_REVIEW_PREFIX) === true + ) +} + +export function isPolicyApprovalForHead( + review: PullRequestReview, + identity: string, + headSha: string +): boolean { + return ( + isPolicyReview(review, identity) && + review.state === 'APPROVED' && + review.commit_id === headSha + ) +} + +export function activePolicyApprovals( + reviews: PullRequestReview[], + identity: string +): PullRequestReview[] { + return reviews.filter( + (review) => isPolicyReview(review, identity) && review.state === 'APPROVED' + ) +} + +export function policyReviewFloor( + reviews: PullRequestReview[], + identity: string +): SubmittedReview | undefined { + return reviews + .filter( + (review): review is SubmittedReview => + isPolicyReview(review, identity) && + review.submitted_at !== undefined && + !Number.isNaN(Date.parse(review.submitted_at)) + ) + .sort( + (left, right) => + Date.parse(left.submitted_at) - Date.parse(right.submitted_at) + )[0] +} + +function hasHeadPolicyApproval( + reviews: PullRequestReview[], + identity: string, + headSha: string | undefined +): boolean { + return ( + headSha !== undefined && + reviews.some((review) => isPolicyApprovalForHead(review, identity, headSha)) + ) +} + +function authorizationFailure({ + pull, + reviews, + lane, + labelEvent +}: EligibilityContext): string | undefined { + const { identity, trustedAuthors, approvalLabel } = lane.approval + const author = pull.user?.login?.toLowerCase() ?? 'unknown' + if (author === identity) { + return 'the approval identity cannot approve its own pull request.' + } + if (trustedAuthors.includes(author)) return + if (!hasLabel(pull, approvalLabel)) { + return `@${author} is not trusted and ${approvalLabel} is not applied.` + } + if ( + isAuthorizedLabelEvent(lane, labelEvent) || + hasHeadPolicyApproval(reviews, identity, pull.head?.sha) + ) { + return + } + return `@${author} is not trusted and ${approvalLabel} lacks a current authorized event; re-run the cancelled labeled run or re-apply the label.` +} + +export function eligibilityFailure( + context: EligibilityContext +): string | undefined { + const { pull, reviews, lane, repository, defaultBranch } = context + if (pull.state !== 'open' || pull.draft) { + return 'the pull request is not open and ready for review.' + } + if ( + !isRepository(pull.base?.repo, repository) || + pull.base?.ref !== defaultBranch + ) { + return `the ${lane.id} fast lane applies only to ${defaultBranch}.` + } + if (!isRepository(pull.head?.repo, repository)) { + return `the ${lane.id} fast lane does not apply to fork pull requests.` + } + const authorization = authorizationFailure(context) + if (authorization) return authorization + if (hasLabel(pull, lane.approval.holdLabel)) { + return `${lane.approval.holdLabel} is applied.` + } + if (hasActiveHumanChangeRequest(reviews)) { + return 'an active human change request is present.' + } +} diff --git a/tools/cicd/fast-lane/src/run.ts b/tools/cicd/fast-lane/src/run.ts new file mode 100644 index 00000000000..0246d785c3b --- /dev/null +++ b/tools/cicd/fast-lane/src/run.ts @@ -0,0 +1,29 @@ +import fs from 'node:fs' +import path from 'node:path' +import { fileURLToPath } from 'node:url' + +import { runFastLane } from './automation.ts' +import { loadRuntimeConfig, requiredEnv } from './config.ts' +import { createGitHubClient } from './github.ts' + +function summary(message: string): void { + process.stdout.write(`${message}\n`) + const summaryPath = process.env.GITHUB_STEP_SUMMARY + if (summaryPath) fs.appendFileSync(summaryPath, `${message}\n`) +} + +export async function main(): Promise { + const config = loadRuntimeConfig() + const github = createGitHubClient( + requiredEnv('FAST_LANE_TOKEN'), + config.repository + ) + await runFastLane(github, config, summary) +} + +if ( + process.argv[1] && + fileURLToPath(import.meta.url) === path.resolve(process.argv[1]) +) { + await main() +} diff --git a/tools/cicd/fast-lane/src/types.ts b/tools/cicd/fast-lane/src/types.ts new file mode 100644 index 00000000000..9025271550f --- /dev/null +++ b/tools/cicd/fast-lane/src/types.ts @@ -0,0 +1,82 @@ +export interface FastLaneConfig { + id: string + pathPrefixes: string[] + approval: { + identity: string + trustedAuthors: string[] + approvalLabel: string + trustedLabelers: string[] + holdLabel: string + } +} + +export interface RepositoryRef { + full_name?: string +} + +export interface PullRequest { + number?: number + state?: string + draft?: boolean + node_id?: string + changed_files?: number + user?: { login?: string } + labels?: { name?: string }[] + head?: { sha?: string; repo?: RepositoryRef | null } + base?: { ref?: string; repo?: RepositoryRef | null } +} + +export interface PullRequestFile { + filename?: string + previous_filename?: string + status?: string +} + +export interface PullRequestReview { + id?: number + state?: string + body?: string + commit_id?: string + submitted_at?: string + user?: { login?: string; type?: string } +} + +export type SubmittedReview = PullRequestReview & { submitted_at: string } + +export interface GitHubClient { + request(path: string, options?: RequestInit): Promise + paginate(path: string): Promise + graphql(query: string, variables: Record): Promise +} + +export interface MergeAutomationState { + id: string + headRefOid?: string + mergeStateStatus?: string + autoMergeRequest?: { + enabledAt?: string + enabledBy?: { login?: string } + } | null + mergeQueueEntry?: { + id?: string + enqueuedAt?: string + enqueuer?: { login?: string } + headCommit?: { oid?: string } + } | null +} + +export interface LabelEvent { + actor: string + label: string +} + +export interface RuntimeConfig { + repository: string + pullRequestNumber: number + eventHeadSha: string + labelEvent?: LabelEvent + defaultBranch: string + lane: FastLaneConfig +} + +export type Summary = (message: string) => void