Repository navigation
validation: website fast lane #20155
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
7a4a6c9
a1aa8f6
10d64a6
79e8b14
6d093f9
845307e
17da17b
78b2df0
a471460
b5b3bc7
585d62f
c84bdaf
206eb03
11294dc
339f049
abe4702
c975dd3
0b43ec4
ef0f493
75fc52f
32b249c
5d4b8f1
a15963c
1d4e20d
f95ed20
f3a40b9
fea4612
cc10dac
ddf7011
ef22dfe
964f919
0d3763c
59cd024
e955907
5d85351
6fda68c
cc83981
15144ca
d2056fe
7a01651
e0b0960
1acd80e
877bd26
5b6eed1
9e70fdc
9189923
6f27166
f8d2ff0
dd646a2
294038b
61ca138
32fb3e6
86fe45c
520de83
1938eac
397cc56
bd0fda6
8b2be52
abde041
1a53093
ceadf96
fcb15c3
6644fd5
eab7e2d
cbf77d9
23d3d29
d1ede07
c1b1a64
91e8072
b387448
9ad947a
10e178b
bb496e3
50953ba
d4fbd61
a39b084
69fd67f
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||||
|---|---|---|---|---|---|---|---|---|
| @@ -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 }} | ||||||||
|
Comment on lines
+56
to
+58
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. P3 This job only runs for
Suggested change
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Addressed in |
||||||||
| 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 | ||||||||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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). |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 <url>`). Vercel then stops assigning new production | ||
| deployments, so once the fix has merged, use Undo Rollback (or `vercel promote <url>`) 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. |
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Uh oh!
There was an error while loading. Please reload this page.