Skip to content

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

TypeScript

ci: visual, accessibility and RTL run on main, not on pull request updates (#8877)

Cindy Zhang14fc58723028
diff --git a/.github/scripts/ci-heavy-lanes.test.mjs b/.github/scripts/ci-heavy-lanes.test.mjs
new file mode 100644
index 0000000000..ea706a43a5
--- /dev/null
+++ b/.github/scripts/ci-heavy-lanes.test.mjs
@@ -0,0 +1,141 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Visual, accessibility and RTL run on main, not on pull request updates.
+ * @input CI, Main and Main heavy lanes workflows, and a mocked GitHub API
+ * @output Routing for the heavy owners, the required joins, and Main's
+ * release-check dispatch
+ * @position Node contracts for AST-030 FR12 and DEC-7
+ */
+
+import fs from 'node:fs';
+import {describe, expect, it} from 'vitest';
+import yaml from 'yaml';
+
+const read = name =>
+ yaml.parse(
+ fs.readFileSync(new URL(`../workflows/${name}`, import.meta.url), 'utf8'),
+ );
+const ci = read('ci.yml');
+const heavy = read('main-heavy-lanes.yml');
+const main = read('deploy.yml');
+
+const LABEL = 'ci:heavy-lanes';
+const HEAVY = [
+ 'pr-a11y-guards',
+ 'pr-a11y-specs',
+ 'pr-a11y',
+ 'visual-scout',
+ 'pr-visual',
+ 'pr-rtl-shard',
+ 'pr-rtl-merge',
+ 'pr-rtl',
+];
+const PR_CLAUSE = `(github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, '${LABEL}'))`;
+
+describe('visual, accessibility and RTL owners', () => {
+ // release-check-workflow.test.mjs evaluates them for release-check and
+ // visual-maintenance-workflow.test.mjs for labelled and unlabelled pull
+ // requests; this pins the shape on every owner.
+ it.each(HEAVY)(
+ '%s runs on a pull request only with the ci:heavy-lanes label',
+ name => {
+ const condition = ci.jobs[name].if;
+ expect(condition).toContain(PR_CLAUSE);
+ expect(condition.replaceAll(PR_CLAUSE, '')).not.toContain(
+ "'pull_request'",
+ );
+ },
+ );
+
+ it('leaves the required joins without a heavy owner, so they still report on every pull request', () => {
+ for (const join of ['test', 'build', 'docsite-test']) {
+ const needs = [ci.jobs[join].needs].flat();
+ for (const owner of HEAVY)
+ expect(needs, `${join} needs ${owner}`).not.toContain(owner);
+ }
+ });
+
+ it('adds no trigger: a label takes effect on the next push or reopen', () => {
+ expect(ci.on.pull_request.types).toBeUndefined();
+ });
+});
+
+describe('the release-check on every push to main', () => {
+ const job = heavy.jobs.dispatch;
+ const script = job.steps[0].with.script;
+
+ it('runs on a push to main and may dispatch workflows', () => {
+ expect(heavy.on).toEqual({push: {branches: ['main']}});
+ expect(job.permissions).toEqual({actions: 'write', contents: 'read'});
+ expect(job.steps[0].env.SHA).toBe('${{ github.sha }}');
+ });
+
+ it('throttles in ci.yml: the dispatched checks share one group that never cancels a running check', () => {
+ // GitHub keeps one running and one pending run per group, and a newer
+ // dispatch replaces the pending one, so a burst of merges is checked once.
+ expect(ci.concurrency.group).toContain(
+ "(github.event_name == 'workflow_dispatch' && github.triggering_actor == 'github-actions[bot]' && 'main-heavy-lanes')",
+ );
+ expect(ci.concurrency['cancel-in-progress']).toBe(
+ "${{ github.event_name != 'workflow_dispatch' }}",
+ );
+ expect(heavy.concurrency).toBeUndefined();
+ });
+
+ it("leaves Main's fast checks running for every push", () => {
+ expect(Object.keys(main.jobs)).not.toContain('release-check');
+ expect(JSON.stringify(main)).not.toContain('createWorkflowDispatch');
+ });
+
+ /** Runs the step's script against a fake GitHub API with main at `tip`. */
+ async function run(tip) {
+ const calls = {dispatch: [], notices: []};
+ const github = {
+ rest: {
+ repos: {getBranch: async () => ({data: {commit: {sha: tip}}})},
+ actions: {
+ createWorkflowDispatch: async args => calls.dispatch.push(args),
+ },
+ },
+ };
+ const body = new Function(
+ 'github',
+ 'context',
+ 'core',
+ 'process',
+ `return (async () => {${script}})();`,
+ );
+ await body(
+ github,
+ {repo: {owner: 'meta', repo: 'astryx'}},
+ {notice: m => calls.notices.push(m)},
+ {env: {SHA: sha}},
+ );
+ return calls;
+ }
+
+ const sha = 'a'.repeat(40);
+
+ it('dispatches release-check on main for the exact pushed commit', async () => {
+ expect((await run(sha)).dispatch).toEqual([
+ {
+ owner: 'meta',
+ repo: 'astryx',
+ workflow_id: 'ci.yml',
+ ref: 'main',
+ inputs: {
+ operation: 'release-check',
+ 'release-branch': 'main',
+ 'expected-head': sha,
+ },
+ },
+ ]);
+ });
+
+ it('leaves a commit main has moved past to the newer push', async () => {
+ const calls = await run('b'.repeat(40));
+ expect(calls.dispatch).toEqual([]);
+ expect(calls.notices[0]).toMatch(/newer push/);
+ });
+});
diff --git a/.github/scripts/generate-pr-comment.js b/.github/scripts/generate-pr-comment.js
index a5b87c81c4..c90dc19a78 100644
--- a/.github/scripts/generate-pr-comment.js
+++ b/.github/scripts/generate-pr-comment.js
@@ -38,7 +38,7 @@ let analysis = {
componentStats: {},
totalBundle: {},
};
-let a11yReport = {components: {}};
+let a11yReport = null; // stays null when the audit did not run
try {
analysis = JSON.parse(fs.readFileSync(analysisFile, 'utf8'));
} catch (e) {
diff --git a/.github/scripts/lib/a11y-format.js b/.github/scripts/lib/a11y-format.js
index 55cfa3882f..bd2b189c52 100644
--- a/.github/scripts/lib/a11y-format.js
+++ b/.github/scripts/lib/a11y-format.js
@@ -44,6 +44,11 @@ function formatWcagTags(tags) {
*/
function buildA11ySection(a11yReport, storiesAuditedByComponent) {
let a11ySection = '### Accessibility Audit\n\n';
+ // No report: the audit did not run (pull requests run it only with the
+ // `ci:heavy-lanes` label, spec:AST-030 FR12). Never claim a clean result.
+ if (!a11yReport) {
+ return a11ySection + '**Status:** The accessibility audit did not run on this pull request. It runs after merges to `main` and before each release; pull requests that touch components run it with the `ci:heavy-lanes` label.\n\n';
+ }
const totalViolations = Object.values(a11yReport.components || {})
.reduce((sum, comp) => sum + (comp.violations?.length || 0), 0);
diff --git a/.github/scripts/lib/a11y-format.test.mjs b/.github/scripts/lib/a11y-format.test.mjs
index a0acaa4e7f..a2ee2983fd 100644
--- a/.github/scripts/lib/a11y-format.test.mjs
+++ b/.github/scripts/lib/a11y-format.test.mjs
@@ -14,6 +14,10 @@ describe('buildA11ySection', () => {
expect(buildA11ySection({components: {}})).toContain('No accessibility violations detected');
});
+ it('says the audit did not run when there is no report', () => {
+ expect(buildA11ySection(null)).toContain('did not run on this pull request');
+ });
+
it('lists a violation with its rule, story count, and help link', () => {
const section = buildA11ySection(
report([
diff --git a/.github/scripts/lib/pr-preview.mjs b/.github/scripts/lib/pr-preview.mjs
index edaca230c3..5cda0584b8 100644
--- a/.github/scripts/lib/pr-preview.mjs
+++ b/.github/scripts/lib/pr-preview.mjs
@@ -558,14 +558,6 @@ export async function reconcilePrComment({
let body;
if (analysisReady) {
- let resolvedA11yPath = a11yPath;
- if (!fs.existsSync(resolvedA11yPath)) {
- resolvedA11yPath = path.resolve('a11y-empty.json');
- fs.writeFileSync(
- resolvedA11yPath,
- '{"components":{},"summary":{"componentsAudited":0,"totalViolations":0}}',
- );
- }
const args = [
generator,
'--analysis',
@@ -573,8 +565,9 @@ export async function reconcilePrComment({
...(trustedBaseStats({baseStatsPath, identity, core})
? ['--base-stats', baseStatsPath]
: []),
- '--a11y',
- resolvedA11yPath,
+ // No report means the audit did not run (it runs on main and release
+ // checks, or with the ci:heavy-lanes label); the comment says so.
+ ...(fs.existsSync(a11yPath) ? ['--a11y', a11yPath] : []),
...(fs.existsSync(visualPath) ? ['--visual', visualPath] : []),
...(storybook ? ['--storybook-url', `${previewOrigin}/storybook/`] : []),
...(sandbox ? ['--sandbox-url', `${previewOrigin}/sandbox/`] : []),
diff --git a/.github/scripts/lib/pr-preview.test.mjs b/.github/scripts/lib/pr-preview.test.mjs
index 51baf296d9..9104e2eaf6 100644
--- a/.github/scripts/lib/pr-preview.test.mjs
+++ b/.github/scripts/lib/pr-preview.test.mjs
@@ -159,7 +159,7 @@ function githubFixture({value = identity(), comments = []} = {}) {
return {github, state};
}
-function fixture(value = identity(), {analysis = true} = {}) {
+function fixture(value = identity(), {analysis = true, a11y = true} = {}) {
const root = fs.mkdtempSync(path.join(os.tmpdir(), 'pr-preview-'));
roots.push(root);
const paths = {
@@ -192,10 +192,12 @@ function fixture(value = identity(), {analysis = true} = {}) {
}),
);
}
- fs.writeFileSync(
- paths.a11y,
- '{"components":{},"summary":{"componentsAudited":0,"totalViolations":0}}',
- );
+ if (a11y) {
+ fs.writeFileSync(
+ paths.a11y,
+ '{"components":{},"summary":{"componentsAudited":0,"totalViolations":0}}',
+ );
+ }
return paths;
}
@@ -203,6 +205,7 @@ async function reconcile({
value = identity(),
previewAvailable = false,
analysis = true,
+ a11y = true,
comments = [],
githubFixtureValue = value,
createIfMissing,
@@ -210,7 +213,7 @@ async function reconcile({
execute,
baseStats,
} = {}) {
- const paths = fixture(value, {analysis});
+ const paths = fixture(value, {analysis, a11y});
const baseStatsPath = path.join(
path.dirname(paths.analysis),
'size-base.json',
@@ -826,6 +829,12 @@ describe('PR comment preview reconciliation', () => {
expect(result.body).not.toContain('facebook.github.io/astryx/pr/');
});
+ it('says the accessibility audit did not run when there is no report', async () => {
+ const {result} = await reconcile({a11y: false});
+ expect(result.body).toContain('did not run on this pull request');
+ expect(result.body).not.toContain('No accessibility violations detected');
+ });
+
it('keeps current trustworthy analysis when source CI fails', async () => {
const value = identity({sourceConclusion: 'failure'});
const {result} = await reconcile({value});
diff --git a/.github/scripts/release-check-workflow.test.mjs b/.github/scripts/release-check-workflow.test.mjs
index ae6e965ad9..e918984dd8 100644
--- a/.github/scripts/release-check-workflow.test.mjs
+++ b/.github/scripts/release-check-workflow.test.mjs
@@ -74,11 +74,17 @@ function runs(
branch = releaseBranch,
needs = dependencies(job),
cancelled = false,
+ labels = [],
} = {},
) {
const expression = (job.if ?? 'true')
.replace(/^\$\{\{\s*|\s*\}\}$/g, '')
- .replace(/needs\.([a-z][a-z0-9-]*)/g, 'needs["$1"]');
+ .replace(/needs\.([a-z][a-z0-9-]*)/g, 'needs["$1"]')
+ // GitHub's object filter: `labels.*.name` lists the labels' names.
+ .replace(
+ /contains\(github\.event\.pull_request\.labels\.\*\.name, '([^']+)'\)/g,
+ "(github.event.pull_request?.labels ?? []).some(label => label.name === '$1')",
+ );
// GitHub injects success() unless the expression has a status function.
if (
!/\b(always|cancelled|success|failure)\(/.test(expression) &&
@@ -93,7 +99,10 @@ function runs(
'cancelled',
`return Boolean(${expression});`,
)(
- {event_name: event},
+ {
+ event_name: event,
+ event: {pull_request: {labels: labels.map(name => ({name}))}},
+ },
{operation, 'release-branch': branch},
needs,
() => true,
diff --git a/.github/scripts/visual-gate/README.md b/.github/scripts/visual-gate/README.md
index 592cb4a68b..7a192fb0eb 100644
--- a/.github/scripts/visual-gate/README.md
+++ b/.github/scripts/visual-gate/README.md
@@ -1,7 +1,10 @@
# Storybook visual regression
Every visual-regression test uses the shared Storybook framework and
-`.github/workflows/ci.yml` → `pr-visual` (**Stable visual regression**).
+`.github/workflows/ci.yml` → `pr-visual` (**Stable visual regression**). It runs
+in `release-check`, which `main-heavy-lanes.yml` dispatches after merges to
+`main` (a burst is checked once, at its newest commit) and the release gate dispatches before a cut; a pull request runs it only
+with the `ci:heavy-lanes` label (AST-030 FR12, DEC-7).
[AST-030 FR12](../../../docs/specs/AST-030/spec.md) owns this requirement.
Add coverage to that owner, not to a new component, package, theme, scheduled,
post-CI, or post-merge workflow.
@@ -24,8 +27,7 @@ cancelled, and skipped work is not release evidence.
This changes when and where release evidence runs, not finding policy: visual
`changed` still requires review, a11y fails on new baseline violations, and RTL
findings remain soft while report completeness is mandatory. The dispatch does
-not capture baseline candidates, promote baselines, publish previews, or replace
-PR checks. It runs only on request, not every push. `visual-release-report` holds
+not capture baseline candidates, promote baselines, or publish previews. `visual-release-report` holds
the visual evidence for that exact run/attempt.
PR accessibility is intentionally smaller: explicit changed-component axe scope
diff --git a/.github/scripts/visual-maintenance-workflow.test.mjs b/.github/scripts/visual-maintenance-workflow.test.mjs
index 9f874b287a..00c9fc16ef 100644
--- a/.github/scripts/visual-maintenance-workflow.test.mjs
+++ b/.github/scripts/visual-maintenance-workflow.test.mjs
@@ -31,11 +31,17 @@ function runs(
operation = 'capture',
needs = {},
cancelled = false,
+ labels = [],
} = {},
) {
const expression = (job.if ?? 'true')
.replace(/^\$\{\{\s*|\s*\}\}$/g, '')
- .replace(/needs\.([a-z][a-z0-9-]*)/g, 'needs["$1"]');
+ .replace(/needs\.([a-z][a-z0-9-]*)/g, 'needs["$1"]')
+ // GitHub's object filter: `labels.*.name` lists the labels' names.
+ .replace(
+ /contains\(github\.event\.pull_request\.labels\.\*\.name, '([^']+)'\)/g,
+ "(github.event.pull_request?.labels ?? []).some(label => label.name === '$1')",
+ );
if (!/\b(always|cancelled|success|failure)\(/.test(expression)) {
if (
cancelled ||
@@ -51,7 +57,10 @@ function runs(
'cancelled',
`return Boolean(${expression});`,
)(
- {event_name: event},
+ {
+ event_name: event,
+ event: {pull_request: {labels: labels.map(name => ({name}))}},
+ },
{operation},
needs,
() => true,
@@ -106,15 +115,18 @@ describe('CI baseline maintenance routing', () => {
expect(runs(visual, {needs})).toBe(false);
});
- it('preserves focused PR routing when the maintenance guard is skipped', () => {
+ it('preserves focused PR routing on an opted-in pull request when the maintenance guard is skipped', () => {
const needs = dependencies(visual);
needs['maintenance-request'].result = 'skipped';
- expect(runs(visual, {event: 'pull_request', needs})).toBe(true);
- needs['check-components'].outputs.has_stable_visual = 'false';
+ const optedIn = {event: 'pull_request', needs, labels: ['ci:heavy-lanes']};
+ expect(runs(visual, optedIn)).toBe(true);
+ // Without the opt-in label a pull request update runs no visual owner.
expect(runs(visual, {event: 'pull_request', needs})).toBe(false);
+ needs['check-components'].outputs.has_stable_visual = 'false';
+ expect(runs(visual, optedIn)).toBe(false);
needs['check-components'].outputs.has_stable_visual = 'true';
needs['build-storybook'].result = 'failure';
- expect(runs(visual, {event: 'pull_request', needs})).toBe(false);
+ expect(runs(visual, optedIn)).toBe(false);
expect(runs(visual, {event: 'merge_group', needs})).toBe(false);
});
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index ef868ed8e2..00d9723e0a 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -46,11 +46,20 @@ permissions: {}
# `ci-duration` reports each job's run time and the run's span. Split a job
# that nears the limit (shard, scope, cache); do not raise it.
#
+# Visual, accessibility and RTL owners (pr-a11y*, visual-scout, pr-visual,
+# pr-rtl*) do not run on pull request updates: they run for release-check,
+# which the Main heavy lanes workflow (main-heavy-lanes.yml) dispatches on every
+# push to main and the release gate dispatches before a cut, and on a pull request labelled `ci:heavy-lanes` (add the label,
+# then push or close and reopen). A main failure is fixed forward
+# (spec:AST-030 FR12, DEC-7).
+#
# One group per pull request (a fork's branch name can repeat across forks),
# so a new push cancels the superseded run. Merge-queue entries and dispatches
-# get their own groups and are never cancelled by a pull request.
+# get their own groups and are never cancelled by a pull request. The
+# release-checks main-heavy-lanes.yml dispatches (as github-actions[bot]) share
+# one group: one runs, the newest waits, and a running check is never cancelled.
concurrency:
- group: 'ci-${{ github.event.pull_request.number || github.event.merge_group.head_sha || github.run_id }}'
+ group: "ci-${{ github.event.pull_request.number || github.event.merge_group.head_sha || (github.event_name == 'workflow_dispatch' && github.triggering_actor == 'github-actions[bot]' && 'main-heavy-lanes') || github.run_id }}"
cancel-in-progress: ${{ github.event_name != 'workflow_dispatch' }}
jobs:
@@ -1533,7 +1542,7 @@ jobs:
pr-a11y-guards:
name: pr-a11y (audit and guards)
needs: [build-storybook, check-components]
- if: (github.event_name == 'pull_request' || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check')) && needs.check-components.outputs.has_components == 'true'
+ if: ((github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'ci:heavy-lanes')) || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check')) && needs.check-components.outputs.has_components == 'true'
runs-on: 2-core-ubuntu-arm
timeout-minutes: ${{ github.event_name == 'workflow_dispatch' && 360 || 15 }}
permissions:
@@ -1640,7 +1649,7 @@ jobs:
pr-a11y-specs:
name: pr-a11y (browser specs)
needs: [build-storybook, check-components]
- if: (github.event_name == 'pull_request' || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check')) && needs.check-components.outputs.has_components == 'true'
+ if: ((github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'ci:heavy-lanes')) || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check')) && needs.check-components.outputs.has_components == 'true'
runs-on: 2-core-ubuntu-arm
timeout-minutes: ${{ github.event_name == 'workflow_dispatch' && 360 || 15 }}
permissions:
@@ -1709,7 +1718,7 @@ jobs:
# Stable required context joining the scoped audit/guards and browser specs.
pr-a11y:
needs: [check-components, pr-a11y-guards, pr-a11y-specs]
- if: ${{ always() && (github.event_name == 'pull_request' || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check')) && needs.check-components.outputs.has_components == 'true' }}
+ if: ${{ always() && ((github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'ci:heavy-lanes')) || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check')) && needs.check-components.outputs.has_components == 'true' }}
runs-on: ubuntu-slim
timeout-minutes: 5
permissions:
@@ -2071,7 +2080,7 @@ jobs:
!cancelled() &&
needs.build-storybook.result == 'success' &&
needs.check-components.result == 'success' &&
- ((github.event_name == 'pull_request' &&
+ (((github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'ci:heavy-lanes')) &&
needs.check-components.outputs.has_stable_visual == 'true' &&
needs.check-components.outputs.broad_stable_visual == 'true') ||
(github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'))
@@ -2142,7 +2151,7 @@ jobs:
[build-storybook, check-components, maintenance-request, visual-scout]
if: >-
!cancelled() &&
- ((github.event_name == 'pull_request' &&
+ (((github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'ci:heavy-lanes')) &&
needs.build-storybook.result == 'success' &&
needs.check-components.result == 'success' &&
needs.check-components.outputs.has_stable_visual == 'true') ||
@@ -2420,7 +2429,7 @@ jobs:
name: pr-rtl (${{ matrix.package }}${{ matrix.parts > 1 && format(' {0}/{1}', matrix.part, matrix.parts) || '' }})
needs: [build-storybook, check-components]
if: >-
- (github.event_name == 'pull_request' ||
+ ((github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'ci:heavy-lanes')) ||
(github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check')) &&
(needs.check-components.outputs.has_rtl_components == 'true' ||
needs.check-components.outputs.has_rtl_harness == 'true' ||
@@ -2604,7 +2613,7 @@ jobs:
needs: [build-storybook, check-components, pr-rtl-shard]
if: >-
always() && !cancelled() &&
- (github.event_name == 'pull_request' ||
+ ((github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'ci:heavy-lanes')) ||
(github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check')) &&
(needs.check-components.outputs.has_rtl_components == 'true' ||
needs.check-components.outputs.has_rtl_harness == 'true' ||
@@ -2692,7 +2701,7 @@ jobs:
# Stable required context joining the five package shards above.
pr-rtl:
needs: [check-scope, check-components, pr-rtl-shard, pr-rtl-merge]
- if: ${{ always() && !cancelled() && ((github.event_name == 'pull_request' && needs.check-scope.outputs.spec_only != 'true') || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check')) }}
+ if: ${{ always() && !cancelled() && (((github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'ci:heavy-lanes')) && needs.check-scope.outputs.spec_only != 'true') || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check')) }}
runs-on: ubuntu-slim
timeout-minutes: 5
steps:
diff --git a/.github/workflows/main-heavy-lanes.yml b/.github/workflows/main-heavy-lanes.yml
new file mode 100644
index 0000000000..83460f3e61
--- /dev/null
+++ b/.github/workflows/main-heavy-lanes.yml
@@ -0,0 +1,48 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+
+# Visual, accessibility and RTL run on main, not on every pull request update
+# (spec:AST-030 FR12, DEC-7): a push to main dispatches ci.yml's canonical
+# release-check on its exact commit; that run is main's visual/a11y/RTL result,
+# and a failure is fixed forward. ci.yml runs one such check at a time and keeps
+# only the newest waiting, so a burst of merges is checked once, at its newest
+# commit. Main's own fast checks (deploy.yml) still run for every push. The
+# release gate's exact-commit release-check before a cut is unchanged.
+name: Main heavy lanes
+
+on:
+ push:
+ branches: ['main']
+
+permissions: {}
+
+jobs:
+ dispatch:
+ runs-on: ubuntu-slim
+ timeout-minutes: 5
+ permissions:
+ actions: write
+ contents: read
+ steps:
+ - name: Dispatch the visual, accessibility and RTL release-check for this commit
+ uses: actions/github-script@v9
+ env:
+ SHA: ${{ github.sha }}
+ with:
+ script: |
+ const sha = process.env.SHA;
+ const {data} = await github.rest.repos.getBranch({...context.repo, branch: 'main'});
+ if (data.commit.sha !== sha) {
+ core.notice(`main moved past ${sha.slice(0, 7)}; the newer push's check covers it.`);
+ return;
+ }
+ // ci.yml queues these dispatches in one group (one running, one
+ // waiting; a newer one replaces the waiting one). A merge landing
+ // between the tip check above and this call makes the run check out
+ // the newer commit and fail its exact-head check; the newer push's
+ // own dispatch then checks that commit.
+ await github.rest.actions.createWorkflowDispatch({
+ ...context.repo,
+ workflow_id: 'ci.yml',
+ ref: 'main',
+ inputs: {operation: 'release-check', 'release-branch': 'main', 'expected-head': sha},
+ });
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 324c208e91..41529dd712 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -385,8 +385,9 @@ Two repo-side rules worth restating here:
WAI-ARIA APG patterns and are tested once; a bespoke reimplementation of
one is a review reject.
- CI is the enforcement layer, not a replacement for the checklist: the
- `pr-a11y` job in `ci.yml` runs an axe audit on every PR that touches
- components, a weekly workflow scans the full component surface, and the
+ `pr-a11y` job in `ci.yml` runs an axe audit after merges to `main` and
+ before each release (and on a pull request labelled `ci:heavy-lanes`), a
+ weekly workflow scans the full component surface, and the
`useAnnounce` lint rule rejects hand-wired `aria-live` regions. axe only
catches static, DOM-level issues — keyboard behavior, focus management, and
announcement timing are exactly what the checklist and the component's unit
@@ -531,7 +532,9 @@ any other value:
// @pr-a11y release-only never on a PR; the release check runs it
```
-`pnpm test:a11y-contract:pr origin/main --dry-run` prints what a pull request
+These routes apply when a pull request runs the accessibility owner, which it
+does only with the `ci:heavy-lanes` label; `main` and release checks run every
+spec. `pnpm test:a11y-contract:pr origin/main --dry-run` prints what a pull request
from your branch would run (component tokens need CI's `analysis.json`; without
it the runner says so and leaves those specs out). A spec writes its receipts under
`test-results/<name>/` or, for a component audit, a top-level
@@ -544,8 +547,10 @@ component set, or has no audit spec has an entry in
### Accessibility audits
-PRs that touch components run an axe-core audit (the `pr-a11y` CI job) over
-the Storybook stories of the changed components. The job **fails** when it
+Merges to `main` (checked at the newest commit of a burst), every release
+check, and a PR labelled `ci:heavy-lanes`
+that touches components run an axe-core audit (the `pr-a11y` CI job); on a PR
+it covers the Storybook stories of the changed components. The job **fails** when it
finds a violation that is not listed in the checked-in baseline,
`.github/a11y-baseline.json`. Violations are keyed
`Component::Story::rule-id`, so unrelated markup churn does not invalidate
@@ -607,14 +612,14 @@ not copying its assertions — see the package README and
### RTL audits
-PRs that touch components also run an RTL audit (`pr-rtl`), scoped to the
-changed components like `pr-a11y`. It is soft-gated — findings show in the job
+The same events run an RTL audit (`pr-rtl`); on a labelled PR it is scoped to
+the changed components like `pr-a11y`. It is soft-gated — findings show in the job
summary but don't block. Repro locally with `pnpm rtl:audit -- --filter Avatar`
(the `--` matters: `pnpm -F` is itself `--filter`). The report classifies every
scoped component as **measured**, **verified N-A**, or a **coverage gap**; an
unexplained all-N-A result is not a clean RTL result. The weekly unfiltered run
-applies the same contract to the full existing roster, while PR CI applies it
-to new and changed components. See `apps/storybook/rtl-audit/README.md`.
+applies the same contract to the full existing roster, while a labelled PR
+applies it to new and changed components. See `apps/storybook/rtl-audit/README.md`.
### Modal close visibility guard
diff --git a/apps/storybook/rtl-audit/README.md b/apps/storybook/rtl-audit/README.md
index e486b1305a..342cd7d039 100644
--- a/apps/storybook/rtl-audit/README.md
+++ b/apps/storybook/rtl-audit/README.md
@@ -18,7 +18,9 @@ auto-discovery layer runs with **zero curated selectors**. There are three
independent auto passes: **D1 (icon-mirror)**, **D5 (positional-mirror)**, and
**D6 (directional-decoration)**.
-> **Scope in CI.** `pr-rtl` passes `--filter` with the components the PR
+> **Scope in CI.** `pr-rtl` runs after merges to `main` and in release checks at
+> full scope, and on a PR only with the `ci:heavy-lanes` label (spec:AST-030
+> FR12). On a labelled PR it passes `--filter` with the components the PR
> touched (from `analysis.json`), matching `pr-a11y`. Eligibility is classified
> by the component policy and package registry loaded from the trusted base ref;
> a missing policy, empty or unmatched path set, unresolved component list, or
@@ -34,8 +36,10 @@ independent auto passes: **D1 (icon-mirror)**, **D5 (positional-mirror)**, and
> policy requires full scope, every manifest must be runnable with an empty
> filter and all five package reports must arrive. A planned scan ending in ERROR
> is incomplete. Missing or malformed analysis/index/manifest input, a noncanonical owner, stale output, a missing or unexpected report, and
-> an all-skipped required matrix all fail closed. An ordinary RTL-harness-only PR runs the fixed `Chart,ChartLegend` routing smoke
-> scope so package discovery and curated aliases cannot skip their own check. The
+> an all-skipped required matrix all fail closed. An RTL-harness-only PR labelled `ci:heavy-lanes` runs the fixed
+> `Chart,ChartLegend` routing smoke scope so package discovery and curated aliases
+> cannot skip their own check; without the label, `main`'s `release-check` covers
+> the harness after merge (spec:AST-030 FR12). The
> full unfiltered sweep also runs weekly in `.github/workflows/rtl-weekly.yml`.
> Omit `--filter` to run it locally. The blocking accessibility audit consumes the
> same package-qualified owner-to-story routes and fails if any selected owner
@@ -263,7 +267,8 @@ without inventing a curated measurement.
- **coverage gap**: every dimension returned N-A and no reason is recorded.
Coverage gaps are findings. This rule applies to the existing full-library
-weekly sweep and to every new or changed component in PR CI. A component with no
+weekly sweep, to main and release checks, and to every new or changed component
+in a labelled PR's CI. A component with no
story is also a gap when it is named by `--filter`; it cannot disappear from the
report merely because there was nothing to render.
diff --git a/docs/architecture/rtl-audit-evidence.md b/docs/architecture/rtl-audit-evidence.md
index b07fc72aef..49d5c84503 100644
--- a/docs/architecture/rtl-audit-evidence.md
+++ b/docs/architecture/rtl-audit-evidence.md
@@ -150,9 +150,13 @@ Lint and rendered audit are complementary:
discoverable icon, decoration, and positional relationships. Component-specific
selectors are used only for semantics generic discovery cannot infer, such as
order, scroll direction, overlay side, or touch-target ownership.
-- **INV7 — CI scope and weekly scope answer different questions.** PR CI checks
- components affected by the change; it may run per package, but the PR result is
- the join of every package scope and cannot pass with one scope missing. The
+- **INV7 — CI scope and weekly scope answer different questions.** The RTL audit
+ runs after merges to `main` (a burst of pushes is checked once, at its newest
+ commit) and before each release, at full scope; a pull
+ request runs it only with the `ci:heavy-lanes` label (spec:AST-030 FR12, DEC-7).
+ When a pull request runs it, it checks components affected by the change; it
+ may run per package, but the PR result is the join of every package scope and
+ cannot pass with one scope missing. The
scheduled unfiltered audit checks the full live roster and shared regressions.
Neither silently replaces the other.
- **INV8 — Applicable evidence invalidates N/A.** A new applicable automatic or
diff --git a/docs/specs/AST-030/spec.md b/docs/specs/AST-030/spec.md
index b42e50e577..55468621a9 100644
--- a/docs/specs/AST-030/spec.md
+++ b/docs/specs/AST-030/spec.md
@@ -185,8 +185,13 @@ they are separately named.
its exact event SHA. It MUST run the canonical `pr-visual` (**Stable visual
regression**), `pr-a11y`, and `pr-rtl` owners with full scope: the closed stable
visual plan and unfiltered accessibility/RTL component rosters. Changed-file,
- focused, smoke, and no-op paths MUST NOT narrow release checks. PR a11y MUST
- remain scoped to changed components plus fast interaction guards; full a11y
+ focused, smoke, and no-op paths MUST NOT narrow release checks. On a pull
+ request, the visual (`visual-scout`, `pr-visual`), accessibility (`pr-a11y`
+ with its guards and specs) and RTL (`pr-rtl` with its legs) owners MUST run
+ only when the pull request carries the `ci:heavy-lanes` label at the event; a
+ pull request update without it runs none of them, and no required context
+ depends on them. An opted-in PR's a11y MUST remain scoped to changed components
+ plus fast interaction guards; full a11y
sweeps, whole-repository spec-test contracts, and their evidence uploads MUST
run only for `release-check` in this workflow. Missing,
failed, cancelled, or skipped required work MUST block the release-check join.
@@ -198,7 +203,14 @@ they are separately named.
later commits remain next-release input. A rewrite or divergence that removes
the checked SHA from current `main` history invalidates the receipt.
This replaces constituent-PR-only release gating, not the canonical checks'
- existing finding policies. Release checks MUST NOT run on every push, capture
+ existing finding policies. A main-push workflow MUST dispatch that
+ release-check for every push to `main`, bound to the pushed commit; the
+ dispatched checks share one concurrency group that never cancels a running
+ check: at most one runs and one waits, and a burst of pushes is checked once,
+ at its newest commit. A commit `main` has already moved past leaves its check
+ to the newer push. That release-check run is main's result, and a failure is
+ fixed forward by an atomic pull request. Main's own fast
+ checks still run for every push. Release checks MUST NOT capture
baseline candidates, publish baselines, or use a separate daily workflow or
retroactive acceptance status.
Deployment, accessibility, RTL, and vibe evidence MAY retain their workflows
@@ -208,22 +220,25 @@ they are separately named.
while preserving legitimate non-visual artifact use.
- **FR13 — Broad CI on a pull request runs what the change reaches.** On a
`pull_request` event whose trusted classification finds no shared
- infrastructure, broad CI keeps every owner and required context and narrows
- what those owners run. The Vitest test owner runs the tests whose module graph
+ infrastructure, broad CI keeps every required context and every owner FR12
+ routes to a pull request, and narrows what those owners run. The Vitest test owner runs the tests whose module graph
reaches a changed file, against the merge commit's base parent, plus every test
that reads repository sources through the file system, directly or through a
module it imports; a computed `import()`, a child process, or a library that
reads sources for it (the TypeScript compiler, a bundler) counts as reading
sources; and every test that loads a changed workspace package from its build,
- by the package's name or a path into its `dist/`. The visual and RTL
- owners audit one affected set of component folders: the changed components
+ by the package's name or a path into its `dist/`. When a pull request runs
+ them (FR12: only with the `ci:heavy-lanes` label), the visual and RTL owners
+ audit one affected set of component folders: the changed components
and their reverse dependents, the folders of the components, in any package,
whose built bundle, `import()` targets included, reaches a changed module.
Visual audits each dependent folder that has a stable story, and runs the
whole plan when the dependents exceed its focused budget or none has one; RTL
audits every component each of those folders implements. A Changeset renders nothing and widens no audit. A changed module that no component bundle holds adds none, and without
- a readable build the audits run in full. PR accessibility stays scoped to
- changed components (FR12). Shared infrastructure runs the full suite: root
+ a readable build the audits run in full. PR accessibility, when it runs, stays
+ scoped to changed components (FR12). Shared infrastructure runs the full suite of
+ the owners the pull request runs (visual, accessibility and RTL only with the
+ `ci:heavy-lanes` label, FR12): root
dependency manifests and lockfile, root configuration, a package's manifest,
build or test configuration and test setup, `internal/` (the test harness
included), `theme-build` paths (tokens and themes), Storybook configuration,
@@ -239,8 +254,10 @@ they are separately named.
on the repository's supported Node and runner versions.
- Unsupported behavior: incomplete or unavailable classification receives no fast
path and runs broad CI.
-- Browser evidence: routing itself has no visual claim; browser checks remain
- mandatory whenever their owning surface is present or scope is uncertain.
+- Browser evidence: routing itself has no visual claim; the browser checks FR12
+ routes to a pull request remain mandatory whenever their owning surface is
+ present or scope is uncertain, and visual, accessibility and RTL run on `main`
+ and release checks (FR12).
## Current-state impact
@@ -349,15 +366,17 @@ surface” exception.
Run release evidence against an exact commit in current `main` history, not only
constituent PR heads. Use an explicit release-time dispatch in `ci.yml` so full
-visual, accessibility, and RTL checks do not run on every main push. Reuse
-existing test/build owners, keep their finding policies, and fail closed on
-incomplete scope, missing work, or when the checked commit is no longer in
-current `main` history. Baseline capture and the reviewed pull request that
+visual, accessibility, and RTL checks do not run on every main push (DEC-7
+supersedes this sentence: they run after merges to `main`). Reuse existing
+test/build owners, keep their finding policies, and fail closed on incomplete
+scope, missing work, or when the checked commit is no longer in current `main`
+history.
+Baseline capture and the reviewed pull request that
versions an accepted candidate remain separate operations.
-PR accessibility remains a scoped, fast check: audit only explicitly resolved
-changed component owners and retain the fast modal-close, theme-var, and story-play
-browser guards. Never widen a PR to the exhaustive accessibility sweep because a
+PR accessibility, when a pull request runs it (DEC-7), is a scoped, fast check:
+audit only explicitly resolved changed component owners and retain the fast
+modal-close, theme-var, and story-play browser guards. Never widen a PR to the exhaustive accessibility sweep because a
shared path changed or the component set is empty. Missing or approximate analysis
fails the scoped check rather than silently claiming no work. Multi-component
folders expand only to their own canonical component owners or existing umbrella
@@ -366,10 +385,35 @@ accessibility roster and the whole-repository spec-test contracts and their
evidence uploads run only on `release-check` in this workflow.
The release path retains the complete suite and cannot substitute a scoped result.
-Rejected: a separate workflow, per-push full audits, and treating a maintenance
+Rejected: a separate workflow, per-push full audits (DEC-7 supersedes this for
+pushes to `main`), and treating a maintenance
capture, skipped check, a checked SHA no longer in current `main` history, or
retroactive status as release evidence.
+### DEC-7 — Visual, accessibility and RTL run on main, not on pull request updates
+
+**Reference:** `spec:AST-030/DEC-7`
+**Decider:** `cixzhang`, `2026-10-28`
+
+Run the visual, accessibility and RTL owners on every push to `main`, through
+the same exact-commit `release-check` the release gate uses, and before a cut;
+a pull request runs them only when it opts in with the `ci:heavy-lanes` label. Main-push checks are throttled: one runs at a time, a
+burst of pushes collapses to its newest commit, and a running check is never
+cancelled, so every check that starts finishes.
+Pull request updates keep the fast checks and every required context; the
+modal-close, theme-var and story-play guards are steps of the accessibility
+owner, so they run with it, after merge or on a labelled pull request. A
+failure on `main` is repaired forward with an atomic pull request, not reverted
+first. This supersedes DEC-5's choice to keep these checks off main pushes:
+running the browser suites on every update of every open pull request costs
+far more than running them once per merge burst on `main`. The label opts a
+pull request into the head-scoped owners FR13 describes; it adds no run of its
+own, and the merged result is checked on `main`, so it is not
+the label-triggered full run DEC-6 rejects.
+
+Rejected: keeping the suites on every pull request update (spend); a separate
+scheduled or daily owner (FR12 keeps one canonical workflow).
+
### DEC-6 — Pull requests run what the change reaches; full runs stay where landing is decided
**Reference:** `spec:AST-030/DEC-6`
@@ -379,7 +423,9 @@ A pull request's Vitest legs and browser audits follow what its change reaches:
the module graph for tests and built-bundle reach for components. Tests that
read sources through the file system run whole, because no import reaches what
they read. Shared infrastructure, uncertainty, `main`, merge-group entries and
-release checks run everything, so no landing or release gate narrows.
+release checks run everything, so no landing or release gate narrows; a pull
+request runs the visual, accessibility and RTL owners only with the
+`ci:heavy-lanes` label (DEC-7).
Rejected: a full run triggered by approval, a label or a draft-to-ready change,
which tests the pull request's head rather than the merged result.