Skip to content

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

TypeScript

ci: an agent lane's push runs the fast checks; the heavy suites run when ready and before merge (AST-030 FR20) (#9200)

Cindy Zhang9497856d047a
diff --git a/.github/actions/heavy-caps/action.yml b/.github/actions/heavy-caps/action.yml
index 6a789ab704..58d3e0b8f9 100644
--- a/.github/actions/heavy-caps/action.yml
+++ b/.github/actions/heavy-caps/action.yml
@@ -32,6 +32,7 @@ runs:
if (login.endsWith('[bot]')) return;
// Agent lanes share one login: each branch prefix counts as an author.
+ // The same list as SHARED_AGENT_LOGINS (.github/scripts/ci-pr-gate.mjs).
const shared = ['cixzhang'].includes(login);
const lane = ref => (shared ? ref.split('/')[0] : '');
const mine = ref => lane(ref) === lane(pr.head.ref);
diff --git a/.github/scripts/ci-admission.test.mjs b/.github/scripts/ci-admission.test.mjs
index 68cf212536..729bf81b24 100644
--- a/.github/scripts/ci-admission.test.mjs
+++ b/.github/scripts/ci-admission.test.mjs
@@ -67,14 +67,20 @@ describe('where runs wait', () => {
expect(room.outputs[key]).toBe(`\${{ steps.room.outputs.${key} }}`);
// Every job but the Storybook build reaches admission, directly or through
// the jobs it needs, never only through the build.
+ // heavy-ci, the agent-push deferral decision (spec:AST-030 FR20), is one
+ // slim job beside admission that the build needs.
const BESIDE = 'build-storybook';
- expect(needsOf(ci.jobs[BESIDE])).toEqual(['room']);
+ const DEFERRAL = 'heavy-ci';
+ expect(needsOf(ci.jobs[BESIDE])).toEqual(['room', DEFERRAL]);
+ expect(needsOf(ci.jobs[DEFERRAL])).toEqual(['room']);
const reaches = id =>
needsOf(ci.jobs[id]).some(
- need => need === 'admission' || (need !== BESIDE && reaches(need)),
+ need =>
+ need === 'admission' ||
+ (need !== BESIDE && need !== DEFERRAL && reaches(need)),
);
for (const id of Object.keys(ci.jobs)) {
- if (!['room', 'admission', 'ci-full', BESIDE].includes(id))
+ if (!['room', 'admission', 'ci-full', BESIDE, DEFERRAL].includes(id))
expect(reaches(id), id).toBe(true);
}
});
@@ -237,8 +243,12 @@ describe('peaks', () => {
const closure = new Set();
const visit = name => {
for (const need of needsOf(ci.jobs[name])) {
+ // heavy-ci decides an agent push's deferral and skips for a
+ // release-check (spec:AST-030 FR20).
if (
- ['maintenance-request', 'room', 'admission'].includes(need) ||
+ ['maintenance-request', 'room', 'admission', 'heavy-ci'].includes(
+ need,
+ ) ||
closure.has(need)
)
continue;
@@ -299,9 +309,10 @@ describe('peaks', () => {
});
it('gives a pull request a peak that covers every job it starts at once', () => {
- // The jobs that need only the waits start together the moment admission
- // ends; the Storybook build may still be running then.
- const waits = ['room', 'admission'];
+ // The jobs that need only the waits (and heavy-ci, the deferral decision
+ // that runs only for an agent push; spec:AST-030 FR20) start together the
+ // moment admission ends; the Storybook build may still be running then.
+ const waits = ['room', 'admission', 'heavy-ci'];
const first = Object.keys(ci.jobs).filter(
name =>
!waits.includes(name) &&
diff --git a/.github/scripts/ci-docsite-browser.test.mjs b/.github/scripts/ci-docsite-browser.test.mjs
index 3976f35723..8f2fe75b84 100644
--- a/.github/scripts/ci-docsite-browser.test.mjs
+++ b/.github/scripts/ci-docsite-browser.test.mjs
@@ -30,8 +30,9 @@ describe('docsite-test', () => {
expect(jobs['docsite-data']).toBeUndefined();
expect(jobs['docsite-browser']).toBeUndefined();
// Only CI's run admission, which never skips (ci-admission.test.mjs).
- // room tells it when CI is full (ci-admission.test.mjs).
- expect(owner.needs).toEqual(['room', 'admission']);
+ // room tells it when CI is full (ci-admission.test.mjs); heavy-ci whether
+ // an agent push deferred it (spec:AST-030 FR20).
+ expect(owner.needs).toEqual(['room', 'admission', 'heavy-ci']);
expect(owner['continue-on-error']).toBeUndefined();
// A required context keeps only the draft skip in its condition; an
// outside contributor's run stops at the first step with the reason.
@@ -46,7 +47,9 @@ describe('docsite-test', () => {
);
// After the FR17 gate and the CI-is-full stop (ci-admission.test.mjs).
expect(owner.steps[1].name).toBe('Stop when CI is full');
- expect(owner.steps.findIndex(s => s.id === 'scope')).toBe(3);
+ // Then an agent push's deferral (spec:AST-030 FR20), then the scope.
+ expect(owner.steps[2].name).toBe('Heavy CI deferred');
+ expect(owner.steps.findIndex(s => s.id === 'scope')).toBe(4);
const builds = owner.steps.filter(s =>
/pnpm -F @astryxdesign\/docsite build/.test(s.run ?? ''),
diff --git a/.github/scripts/ci-heavy-deferral.test.mjs b/.github/scripts/ci-heavy-deferral.test.mjs
new file mode 100644
index 0000000000..b26f3125db
--- /dev/null
+++ b/.github/scripts/ci-heavy-deferral.test.mjs
@@ -0,0 +1,532 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file An agent lane's push defers the heavy suites (spec:AST-030 FR20,
+ * DEC-14).
+ *
+ * @input ci.yml, lint.yml and pr-comment.yml, evaluated as Actions would for
+ * each kind of push
+ * @output proofs that a deferred push runs only the fast checks, that every
+ * required context it reaches fails with the reason instead of passing as
+ * skipped, and that every other push, the ready and reopen events and any
+ * later attempt run everything
+ * @position Node contract for the `heavy-ci` decision and the jobs it gates
+ */
+
+import {spawnSync} from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import {describe, expect, it} from 'vitest';
+import yaml from 'yaml';
+
+import {
+ HEAVY_CANDIDATE,
+ HEAVY_DEFERRED,
+ HEAVY_DEFERRED_MESSAGE,
+ HEAVY_RUNS,
+ SHARED_AGENT_LOGINS,
+ ungated,
+} from './ci-pr-gate.mjs';
+
+const read = name =>
+ yaml.parse(
+ fs.readFileSync(
+ path.resolve(import.meta.dirname, '../workflows', name),
+ 'utf8',
+ ),
+ );
+const ci = read('ci.yml');
+const lint = read('lint.yml');
+const prComment = read('pr-comment.yml');
+
+// The jobs that skip on a deferred push.
+const HEAVY = [
+ 'test-ui',
+ 'test-node',
+ 'native-swift-runner',
+ 'test-native-swift',
+ 'run-labels',
+ 'test-build',
+ 'build-storybook',
+ 'pr-interaction',
+ 'pr-interaction-webkit',
+];
+// The required contexts ci.yml reports (spec:AST-030 FR7).
+const REQUIRED = ['test', 'build', 'docsite-test'];
+
+function pushEvent({
+ action = 'synchronize',
+ attempt = '1',
+ login = 'cixzhang',
+ base = 'main',
+ head = 'fix/thing',
+} = {}) {
+ return {
+ event_name: 'pull_request',
+ repository: 'meta/astryx',
+ run_attempt: attempt,
+ base_ref: base,
+ head_ref: head,
+ event: {
+ action,
+ pull_request: {
+ draft: false,
+ user: {login},
+ head: {repo: {full_name: 'meta/astryx'}},
+ labels: [],
+ },
+ },
+ };
+}
+
+/**
+ * Evaluates a job or step condition as Actions would. `needs` maps a job id
+ * to `{result, outputs}`; a condition with no status-check function also
+ * needs every needed job to have succeeded.
+ */
+function evaluate(condition, {github, needs = {}, jobNeeds = []}) {
+ const expression = String(condition)
+ .replace(/^\$\{\{\s*|\s*\}\}$/g, '')
+ .replace(/\.labels\.\*\.name/g, '.labels.map(l => l.name)')
+ .replace(/needs\.([a-z][a-z0-9-]*)/g, 'needs["$1"]');
+ const hasStatus = /\b(always|cancelled|failure|success)\(\)/.test(expression);
+ const needed = [jobNeeds].flat().map(id => needs[id] ?? {result: 'success'});
+ const succeeded = needed.every(need => need.result === 'success');
+ const all = new Proxy(needs, {
+ get: (target, key) => target[key] ?? {result: 'success', outputs: {}},
+ });
+ return Boolean(
+ Function(
+ 'github',
+ 'needs',
+ 'inputs',
+ 'always',
+ 'cancelled',
+ 'success',
+ 'failure',
+ 'startsWith',
+ 'contains',
+ 'fromJSON',
+ `return ${hasStatus ? '' : 'success() && '}(${expression});`,
+ )(
+ github,
+ all,
+ {},
+ () => true,
+ () => false,
+ () => succeeded,
+ () => !succeeded,
+ (value, prefix) => String(value ?? '').startsWith(prefix),
+ (list, item) => list.includes(item),
+ JSON.parse,
+ ),
+ );
+}
+
+/** The `heavy-ci` result and output a push leaves, by its own condition. */
+function heavyCi(github, {specOnly = false} = {}) {
+ if (!evaluate(ci.jobs['heavy-ci'].if, {github}))
+ return {result: 'skipped', outputs: {}};
+ return {
+ result: 'success',
+ outputs: {deferred: specOnly ? 'false' : 'true'},
+ };
+}
+
+/** Whether a job starts, with every need but `heavy-ci` as given. */
+function starts(id, github, {specOnly, others = 'success'} = {}) {
+ const job = ci.jobs[id];
+ const needs = Object.fromEntries(
+ [job.needs ?? []]
+ .flat()
+ .map(need => [
+ need,
+ need === 'heavy-ci'
+ ? heavyCi(github, {specOnly})
+ : {result: others, outputs: {}},
+ ]),
+ );
+ return evaluate(job.if, {github, needs, jobNeeds: job.needs ?? []});
+}
+
+const deferralStep = id =>
+ ci.jobs[id].steps.find(step => step.name === 'Heavy CI deferred');
+
+describe('which pushes defer the heavy suites (spec:AST-030 FR20)', () => {
+ it('is a push to a ready agent-lane pull request into main, in its first attempt', () => {
+ expect(ci.jobs['heavy-ci'].if).toContain(HEAVY_CANDIDATE);
+ expect(evaluate(HEAVY_CANDIDATE, {github: pushEvent()})).toBe(true);
+ });
+
+ it.each([
+ ['marked ready', {action: 'ready_for_review'}],
+ ['opened', {action: 'opened'}],
+ ['reopened', {action: 'reopened'}],
+ ['re-run (the pre-merge run)', {attempt: '2'}],
+ ['from another author', {login: 'someone'}],
+ ['a release merge-back', {head: 'chore/merge-v1.2.3-to-main'}],
+ ])('runs everything when the pull request is %s', (_, event) => {
+ const github = pushEvent(event);
+ expect(evaluate(HEAVY_CANDIDATE, {github})).toBe(false);
+ expect(heavyCi(github).result).toBe('skipped');
+ for (const id of HEAVY) expect(starts(id, github), id).toBe(true);
+ for (const id of REQUIRED) {
+ expect(starts(id, github), id).toBe(true);
+ expect(
+ evaluate(deferralStep(id).if, {
+ github,
+ needs: {'heavy-ci': heavyCi(github)},
+ }),
+ id,
+ ).toBe(false);
+ }
+ });
+
+ it('never defers a release-branch pull request', () => {
+ const github = pushEvent({base: 'release/v1.2.3'});
+ expect(heavyCi(github).result).toBe('skipped');
+ });
+
+ it('names the shared agent logins in one list, the heavy-suite caps included', () => {
+ expect(HEAVY_CANDIDATE).toContain(
+ `fromJSON('${JSON.stringify(SHARED_AGENT_LOGINS)}')`,
+ );
+ const caps = fs.readFileSync(
+ path.resolve(import.meta.dirname, '../actions/heavy-caps/action.yml'),
+ 'utf8',
+ );
+ const listed = /const shared = (\[[^\]]*\])\.includes\(login\)/.exec(
+ caps,
+ )[1];
+ expect(JSON.parse(listed.replaceAll("'", '"'))).toEqual(
+ SHARED_AGENT_LOGINS,
+ );
+ });
+
+ it('runs everything for a spec-only change', () => {
+ const github = pushEvent();
+ for (const id of HEAVY)
+ expect(starts(id, github, {specOnly: true}), id).toBe(true);
+ });
+});
+
+describe('a deferred push', () => {
+ const github = pushEvent();
+
+ it('skips every heavy job', () => {
+ for (const id of HEAVY) {
+ expect(starts(id, github), id).toBe(false);
+ // The deferral sits right after the gate, and ungated() sees past it.
+ expect(String(ci.jobs[id].if), id).toContain(`&& (${HEAVY_RUNS} && (`);
+ expect(ungated(ci.jobs[id].if), id).not.toContain('heavy-ci');
+ }
+ });
+
+ it('still runs the fast checks: typecheck and lint', () => {
+ expect(starts('typecheck', github)).toBe(true);
+ expect(JSON.stringify(ci.jobs.typecheck)).not.toContain('heavy-ci');
+ expect(JSON.stringify(lint)).not.toContain('heavy-ci');
+ });
+
+ it('fails every required context with the reason, never passing as skipped', () => {
+ for (const id of REQUIRED) {
+ // The job starts even though the jobs it joins skipped...
+ expect(starts(id, github, {others: 'skipped'}), id).toBe(true);
+ // ...and its deferral step, which exits 1, runs right after the fork
+ // gate and the CI-is-full stop (and, in `test`, the PR report's
+ // record), so the context fails before any join could pass.
+ const steps = ci.jobs[id].steps;
+ const step = deferralStep(id);
+ const before = steps.slice(0, steps.indexOf(step)).map(item => item.name);
+ expect(before.slice(0, 2), id).toEqual([
+ 'Require a branch in this repository or the ci:run label',
+ 'Stop when CI is full',
+ ]);
+ expect(before.slice(2), id).toEqual(
+ id === 'test'
+ ? [
+ 'Record the deferral for the PR report',
+ 'Upload the deferral for the PR report',
+ ]
+ : [],
+ );
+ expect(step.if).toBe(HEAVY_DEFERRED);
+ expect(
+ evaluate(step.if, {github, needs: {'heavy-ci': heavyCi(github)}}),
+ id,
+ ).toBe(true);
+ expect(step.run, id).toContain(`::error::${HEAVY_DEFERRED_MESSAGE}`);
+ expect(step.run, id).toMatch(/\bexit 1\s*$/);
+ }
+ });
+
+ it('decides with one cheap job that reads the trusted scope', () => {
+ const job = ci.jobs['heavy-ci'];
+ expect(job['runs-on']).toBe('ubuntu-slim');
+ expect(job.outputs.deferred).toBe('${{ steps.decide.outputs.deferred }}');
+ expect(
+ job.steps.some(step => step.uses?.endsWith('/actions/test-scope')),
+ ).toBe(true);
+ for (const id of [...HEAVY, ...REQUIRED])
+ expect([ci.jobs[id].needs].flat(), id).toContain('heavy-ci');
+ });
+
+ it.each([
+ ['true', 'false', ''],
+ ['false', 'true', HEAVY_DEFERRED_MESSAGE],
+ ['', 'true', HEAVY_DEFERRED_MESSAGE],
+ ])(
+ 'defers unless the change is spec-only (spec_only=%s → deferred=%s)',
+ (specOnly, deferred, summary) => {
+ const step = ci.jobs['heavy-ci'].steps.find(item => item.id === 'decide');
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'heavy-ci-'));
+ try {
+ const output = path.join(dir, 'output');
+ const stepSummary = path.join(dir, 'summary');
+ const result = spawnSync(
+ 'bash',
+ ['-e', '-c', step.run.replaceAll(/\$\{\{[^}]*\}\}/g, 'abc')],
+ {
+ cwd: dir,
+ encoding: 'utf8',
+ env: {
+ ...process.env,
+ SPEC_ONLY: specOnly,
+ GITHUB_OUTPUT: output,
+ GITHUB_STEP_SUMMARY: stepSummary,
+ GITHUB_RUN_ID: '7',
+ GITHUB_RUN_ATTEMPT: '1',
+ },
+ },
+ );
+ expect(result.status, result.stderr).toBe(0);
+ expect(fs.readFileSync(output, 'utf8')).toBe(`deferred=${deferred}\n`);
+ expect(
+ fs.existsSync(stepSummary)
+ ? fs.readFileSync(stepSummary, 'utf8')
+ : '',
+ ).toBe(summary ? `${summary}.\n` : '');
+ } finally {
+ fs.rmSync(dir, {recursive: true, force: true});
+ }
+ },
+ );
+});
+
+describe("heavy-ci's skip on every other run", () => {
+ // Actions' implicit success() needs every ancestor, not only the direct
+ // needs, to have succeeded; heavy-ci skips on every run but an agent push,
+ // so any job below it without its own status check would skip too.
+ const needsOf = id => [ci.jobs[id].needs ?? []].flat();
+ const ancestors = (id, seen = new Set()) => {
+ for (const need of needsOf(id))
+ if (!seen.has(need)) {
+ seen.add(need);
+ ancestors(need, seen);
+ }
+ return seen;
+ };
+ const below = Object.keys(ci.jobs).filter(id =>
+ ancestors(id).has('heavy-ci'),
+ );
+
+ it('gives every job below it a status check', () => {
+ expect(below.length).toBeGreaterThan(HEAVY.length);
+ for (const id of below)
+ expect(String(ci.jobs[id].if), id).toMatch(
+ /\b(always|cancelled|success|failure)\(\)/,
+ );
+ });
+
+ /** Every job's start as Actions decides it, ancestors included. */
+ function plan(github, inputs = {}, {full = false} = {}) {
+ const results = {};
+ const order = [];
+ const visit = id => {
+ if (order.includes(id)) return;
+ for (const need of needsOf(id)) visit(need);
+ order.push(id);
+ };
+ Object.keys(ci.jobs).forEach(visit);
+ for (const id of order) {
+ const job = ci.jobs[id];
+ const needs = Object.fromEntries(
+ needsOf(id).map(need => [need, results[need]]),
+ );
+ const all = [...ancestors(id)].map(need => results[need]);
+ const condition = String(job.if ?? 'true')
+ .replace(/^\$\{\{\s*|\s*\}\}$/g, '')
+ .replace(/\.labels\.\*\.name/g, '.labels.map(l => l.name)')
+ .replace(/needs\.([a-z][a-z0-9-]*)/g, 'needs["$1"]');
+ const hasStatus = /\b(always|cancelled|failure|success)\(\)/.test(
+ condition,
+ );
+ const ok = all.every(item => item.result === 'success');
+ const runs =
+ (hasStatus || ok) &&
+ Boolean(
+ Function(
+ 'github',
+ 'needs',
+ 'inputs',
+ 'always',
+ 'cancelled',
+ 'success',
+ 'failure',
+ 'startsWith',
+ 'contains',
+ 'fromJSON',
+ `return (${condition});`,
+ )(
+ github,
+ needs,
+ inputs,
+ () => true,
+ () => false,
+ () => ok,
+ () => !ok,
+ (value, prefix) => String(value ?? '').startsWith(prefix),
+ (list, item) => list.includes(item),
+ JSON.parse,
+ ),
+ );
+ results[id] = {
+ // When CI is full, admission fails at its first step.
+ result: !runs
+ ? 'skipped'
+ : id === 'admission' && full
+ ? 'failure'
+ : 'success',
+ outputs:
+ id === 'run-labels'
+ ? {a11y: 'true', rtl: 'true', visual: 'true'}
+ : id === 'room'
+ ? {full: String(full)}
+ : {},
+ };
+ }
+ return results;
+ }
+
+ it("runs a release-check's every browser owner", () => {
+ const results = plan(
+ {event_name: 'workflow_dispatch', repository: 'meta/astryx', event: {}},
+ {operation: 'release-check', 'release-branch': 'main'},
+ );
+ expect(results['heavy-ci'].result).toBe('skipped');
+ for (const id of [
+ 'build-storybook',
+ 'pr-a11y-shard',
+ 'a11y-contracts-shard',
+ 'pr-a11y-guards',
+ 'pr-a11y-specs',
+ 'pr-rtl-shard',
+ 'pr-a11y-audit',
+ 'release-check',
+ ])
+ expect(results[id].result, id).toBe('success');
+ });
+
+ it('starts no heavy job when CI is full (spec:AST-030 FR16)', () => {
+ // A fork's run with ci:run cannot cancel itself, so only the jobs' own
+ // conditions stop it.
+ const github = pushEvent({login: 'someone'});
+ github.event.pull_request.head.repo.full_name = 'someone/astryx';
+ github.event.pull_request.labels = [{name: 'ci:run'}];
+ const results = plan(github, {}, {full: true});
+ expect(results.admission.result).toBe('failure');
+ expect(results['heavy-ci'].result).toBe('skipped');
+ // test-native-swift always runs to report its runner, as on main.
+ for (const id of HEAVY.filter(item => item !== 'test-native-swift'))
+ expect(results[id].result, id).toBe('skipped');
+ });
+
+ it('runs the suites an opt-in label asks for on a pull request', () => {
+ const github = pushEvent({login: 'someone', action: 'labeled'});
+ github.event.pull_request.labels = [
+ {name: 'ci:run-a11y'},
+ {name: 'ci:run-rtl'},
+ ];
+ const results = plan(github);
+ expect(results['heavy-ci'].result).toBe('skipped');
+ for (const id of ['pr-a11y-guards', 'pr-a11y-specs', 'pr-rtl-shard'])
+ expect(results[id].result, id).toBe('success');
+ });
+});
+
+describe('the PR report on a deferred push', () => {
+ const comment = prComment.jobs.comment;
+
+ it("reads the run attempt's deferral, only for a failed run", () => {
+ const download = comment.steps.find(
+ step => step.id === 'deferral-download',
+ );
+ expect(download.uses).toBe('actions/download-artifact@v8');
+ expect(download.with.name).toBe(
+ 'heavy-ci-deferred-${{ steps.identity.outputs.run_attempt }}',
+ );
+ expect(download.with['run-id']).toBe(
+ '${{ steps.identity.outputs.run_id }}',
+ );
+ expect(download.if).toContain(
+ "steps.identity.outputs.source_conclusion == 'failure'",
+ );
+ expect(download['continue-on-error']).toBe(true);
+ // `test` records it: a failed-jobs re-run repeats `test` (it failed) and
+ // keeps heavy-ci's output, so that attempt has its own record; a full
+ // re-run is a later attempt, which never defers.
+ const steps = ci.jobs.test.steps;
+ const record = steps.find(
+ step => step.name === 'Record the deferral for the PR report',
+ );
+ const upload = steps.find(step =>
+ step.uses?.startsWith('actions/upload-artifact'),
+ );
+ expect(record.if).toBe(HEAVY_DEFERRED);
+ expect(upload.if).toBe(HEAVY_DEFERRED);
+ expect(upload.with.name).toBe(
+ 'heavy-ci-deferred-${{ github.run_attempt }}',
+ );
+ expect(
+ ci.jobs['heavy-ci'].steps.some(step =>
+ step.uses?.startsWith('actions/upload-artifact'),
+ ),
+ ).toBe(false);
+ });
+
+ it('writes the record the report reads', () => {
+ const record = ci.jobs.test.steps.find(
+ step => step.name === 'Record the deferral for the PR report',
+ );
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'heavy-ci-'));
+ try {
+ const result = spawnSync(
+ 'bash',
+ ['-e', '-c', record.run.replaceAll(/\$\{\{[^}]*\}\}/g, 'abc')],
+ {
+ cwd: dir,
+ encoding: 'utf8',
+ env: {...process.env, GITHUB_RUN_ID: '7', GITHUB_RUN_ATTEMPT: '2'},
+ },
+ );
+ expect(result.status, result.stderr).toBe(0);
+ expect(
+ JSON.parse(
+ fs.readFileSync(path.join(dir, 'heavy-ci-deferred.json'), 'utf8'),
+ ),
+ ).toEqual({headSha: 'abc', runId: '7', runAttempt: '2'});
+ } finally {
+ fs.rmSync(dir, {recursive: true, force: true});
+ }
+ });
+
+ it('says the heavy CI was deferred', () => {
+ const publish = comment.steps.find(step => step.id === 'publish');
+ expect(publish.with.script).toContain(HEAVY_DEFERRED_MESSAGE);
+ expect(publish.with.script).toContain(
+ 'heavy-ci-deferred/heavy-ci-deferred.json',
+ );
+ });
+});
diff --git a/.github/scripts/ci-interaction-webkit.test.mjs b/.github/scripts/ci-interaction-webkit.test.mjs
index 707e94dc10..f99f839b58 100644
--- a/.github/scripts/ci-interaction-webkit.test.mjs
+++ b/.github/scripts/ci-interaction-webkit.test.mjs
@@ -59,7 +59,12 @@ describe('WebKit interaction proof routing', () => {
"github.event_name != 'workflow_dispatch' && always() && !cancelled() && needs.room.outputs.full != 'true'",
);
// Admission too: the Storybook build starts beside it (spec:AST-030 FR16).
- expect(webkit.needs).toEqual(['room', 'admission', 'build-storybook']);
+ expect(webkit.needs).toEqual([
+ 'room',
+ 'admission',
+ 'heavy-ci',
+ 'build-storybook',
+ ]);
});
it('stays on a standard runner within the 15-minute budget', () => {
diff --git a/.github/scripts/ci-interaction.test.mjs b/.github/scripts/ci-interaction.test.mjs
index cf7a52b76d..296967dd64 100644
--- a/.github/scripts/ci-interaction.test.mjs
+++ b/.github/scripts/ci-interaction.test.mjs
@@ -50,7 +50,12 @@ describe('interaction proof routing', () => {
"github.event_name != 'workflow_dispatch' && always() && !cancelled() && needs.room.outputs.full != 'true'",
);
// Admission too: the Storybook build starts beside it (spec:AST-030 FR16).
- expect(proofs.needs).toEqual(['room', 'admission', 'build-storybook']);
+ expect(proofs.needs).toEqual([
+ 'room',
+ 'admission',
+ 'heavy-ci',
+ 'build-storybook',
+ ]);
});
it('decides its own scope first, and gates every later step on it', () => {
diff --git a/.github/scripts/ci-native-swift.test.mjs b/.github/scripts/ci-native-swift.test.mjs
index 944ff89dba..5fc0486465 100644
--- a/.github/scripts/ci-native-swift.test.mjs
+++ b/.github/scripts/ci-native-swift.test.mjs
@@ -59,7 +59,7 @@ describe('native Swift routing', () => {
expect(runner.steps.find(s => s.id === 'scope').uses).toBe(
'./.test-scope/.github/actions/test-scope',
);
- expect(swift.needs).toEqual(['native-swift-runner']);
+ expect(swift.needs).toEqual(['heavy-ci', 'native-swift-runner']);
expect(swift['runs-on']).toBe(
`\${{ ${applies} && 'macos-15' || 'ubuntu-slim' }}`,
);
diff --git a/.github/scripts/ci-pr-gate.mjs b/.github/scripts/ci-pr-gate.mjs
index 3b8901f842..14725f9ba0 100644
--- a/.github/scripts/ci-pr-gate.mjs
+++ b/.github/scripts/ci-pr-gate.mjs
@@ -33,13 +33,62 @@ export function gated(condition, gate = PR_CI_GATE) {
return condition.startsWith('${{') ? `\${{ ${wrapped} }}` : wrapped;
}
-/** The job's own condition, without the gate in front. */
+/**
+ * The job's own condition, without the gate in front, nor the heavy-suite
+ * deferral a heavy job adds after it (spec:AST-030 FR20).
+ */
export function ungated(condition) {
- const expression = condition.replace(/^\$\{\{\s*|\s*\}\}$/g, '');
+ let expression = condition.replace(/^\$\{\{\s*|\s*\}\}$/g, '');
for (const gate of [PR_CI_GATE, PR_REPORT_GATE]) {
const prefix = `${gate} && (`;
- if (expression.startsWith(prefix))
- return expression.slice(prefix.length, -1);
+ if (expression.startsWith(prefix)) {
+ expression = expression.slice(prefix.length, -1);
+ break;
+ }
}
+ if (expression.startsWith(`${HEAVY_RUNS} && (`))
+ expression = expression.slice(HEAVY_RUNS.length + 5, -1);
+ if (expression.startsWith(`${HEAVY_ADMITTED} && (`))
+ expression = expression.slice(HEAVY_ADMITTED.length + 5, -1);
return expression;
}
+
+/**
+ * A push that defers the heavy suites (spec:AST-030 FR20, DEC-14): a push to a
+ * ready pull request from the shared agent login, in its first attempt, into
+ * `main`. A release merge-back is never deferred. The `heavy-ci` job runs only
+ * then, and defers unless the change is spec-only.
+ */
+/**
+ * The shared agent logins. The heavy-suite caps
+ * (.github/actions/heavy-caps) list the same logins, and a test holds the two
+ * lists equal.
+ */
+export const SHARED_AGENT_LOGINS = ['cixzhang'];
+
+export const HEAVY_CANDIDATE =
+ "(github.event_name == 'pull_request' && github.event.action == 'synchronize' && " +
+ `github.run_attempt == '1' && contains(fromJSON('${JSON.stringify(SHARED_AGENT_LOGINS)}'), github.event.pull_request.user.login) && ` +
+ "github.base_ref == 'main' && !startsWith(github.head_ref, 'chore/merge-v'))";
+
+/** `heavy-ci` decided to defer this push's heavy suites. */
+export const HEAVY_DEFERRED = "needs.heavy-ci.outputs.deferred == 'true'";
+
+/**
+ * A heavy job's condition after the gate. `heavy-ci` skips for every push it
+ * does not decide, so the job runs then too (`!cancelled()`, not success()).
+ */
+export const HEAVY_RUNS =
+ "!cancelled() && needs.heavy-ci.outputs.deferred != 'true'";
+
+/**
+ * `!cancelled()` above also drops Actions' implicit success check, so a heavy
+ * job that needs admission and had no status check of its own checks
+ * admission itself: when CI is full admission fails, and the job must stop
+ * (spec:AST-030 FR16).
+ */
+export const HEAVY_ADMITTED = "needs.admission.result == 'success'";
+
+/** What a deferred required check and the PR report say. */
+export const HEAVY_DEFERRED_MESSAGE =
+ 'Heavy CI deferred: runs when marked ready and before merge';
diff --git a/.github/scripts/ci-pr-gate.test.mjs b/.github/scripts/ci-pr-gate.test.mjs
index 794c5c70d4..becaebab8a 100644
--- a/.github/scripts/ci-pr-gate.test.mjs
+++ b/.github/scripts/ci-pr-gate.test.mjs
@@ -195,6 +195,21 @@ describe('pull-request CI gate (spec:AST-030 FR17)', () => {
!/always\(\)|cancelled\(\)|failure\(\)/.test(condition)
)
continue;
+ // A job that runs only once a gated job it needs succeeded is gated
+ // through it (its status check keeps an ancestor's skip, such as
+ // heavy-ci's, from skipping it; spec:AST-030 FR20).
+ if (
+ [job.needs ?? []]
+ .flat()
+ .some(
+ need =>
+ condition.includes(`needs.${need}.result == 'success'`) &&
+ startsWithGate(PR_CI_GATE).test(
+ String(value.jobs[need]?.if ?? ''),
+ ),
+ )
+ )
+ continue;
if (
/^(\$\{\{\s*)?(always\(\) && )?github\.event_name == 'workflow_dispatch' &&/.test(
condition,
diff --git a/.github/scripts/ci-test-routing.test.mjs b/.github/scripts/ci-test-routing.test.mjs
index 0eb8d3e1c7..9a3e13e2b2 100644
--- a/.github/scripts/ci-test-routing.test.mjs
+++ b/.github/scripts/ci-test-routing.test.mjs
@@ -786,7 +786,12 @@ describe('ci.yml interaction proofs', () => {
// One fixed runner: out of scope, every step after the scope step skips.
expect(KNOWN_RUNNERS.has(job['runs-on']), job['runs-on']).toBe(true);
// Admission too: the Storybook build starts beside it (spec:AST-030 FR16).
- expect(job.needs).toEqual(['room', 'admission', 'build-storybook']);
+ expect(job.needs).toEqual([
+ 'room',
+ 'admission',
+ 'heavy-ci',
+ 'build-storybook',
+ ]);
const checkout = job.steps.find(
candidate =>
candidate.uses?.startsWith('actions/checkout@') &&
diff --git a/.github/scripts/ci-tooling-routing.test.mjs b/.github/scripts/ci-tooling-routing.test.mjs
index db33e2c47e..d61280333b 100644
--- a/.github/scripts/ci-tooling-routing.test.mjs
+++ b/.github/scripts/ci-tooling-routing.test.mjs
@@ -193,6 +193,7 @@ describe('Node-tooling CI routing', () => {
// room only tells test when CI is full (ci-admission.test.mjs).
expect(ci.jobs.test.needs).toEqual([
'room',
+ 'heavy-ci',
'release-bump',
'test-ui',
'test-node',
@@ -203,6 +204,7 @@ describe('Node-tooling CI routing', () => {
]);
expect(ci.jobs.build.needs).toEqual([
'room',
+ 'heavy-ci',
'build-storybook',
'typecheck',
]);
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 78a04e22f5..b89a74e261 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -490,8 +490,53 @@ jobs:
# code and theme, nothing sent to a document the code navigated to), and
# only the production build has the opaque-origin sandbox at all. The
# spec-only lane validates spec records here, where it always has.
+ # Whether this push defers the heavy suites (spec:AST-030 FR20, DEC-14): a
+ # push to a ready agent-lane pull request (the shared agent login), in its
+ # first attempt, runs only the fast checks (lint, typecheck). The heavy jobs
+ # skip, and the required checks fail with the reason until the pull request
+ # is marked ready or reopened, or its run is re-run in full before merge
+ # (any later attempt runs everything). A spec-only change is never deferred.
+ # Every other run skips this job at once, so it delays nothing; every job
+ # below it carries a status check, so the skip never skips them. It needs
+ # only room, beside admission, so the Storybook build it gates still starts
+ # with room (spec:AST-030 FR16), and like room it holds one slim job.
+ heavy-ci:
+ needs: [room]
+ if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && ((github.event_name == 'pull_request' && github.event.action == 'synchronize' && github.run_attempt == '1' && contains(fromJSON('["cixzhang"]'), github.event.pull_request.user.login) && github.base_ref == 'main' && !startsWith(github.head_ref, 'chore/merge-v')) && needs.room.outputs.full != 'true') }}
+ runs-on: ubuntu-slim
+ timeout-minutes: 5
+ permissions:
+ contents: read
+ pull-requests: read
+ outputs:
+ deferred: ${{ steps.decide.outputs.deferred }}
+ steps:
+ - name: Check out the scope action
+ uses: actions/checkout@v7
+ with:
+ sparse-checkout: .github/actions/test-scope
+ path: .test-scope
+ persist-credentials: false
+
+ - name: Decide this push's scope
+ id: scope
+ uses: ./.test-scope/.github/actions/test-scope
+
+ - name: Defer the heavy suites unless the change is spec-only
+ id: decide
+ env:
+ SPEC_ONLY: ${{ steps.scope.outputs.spec_only }}
+ run: |
+ if [ "$SPEC_ONLY" = true ]; then
+ echo 'deferred=false' >> "$GITHUB_OUTPUT"
+ exit 0
+ fi
+ echo 'deferred=true' >> "$GITHUB_OUTPUT"
+ echo "::notice title=Heavy CI deferred::Heavy CI deferred: runs when marked ready and before merge. Mark the pull request ready, reopen it, or re-run all jobs of this run to run everything."
+ echo "Heavy CI deferred: runs when marked ready and before merge." >> "$GITHUB_STEP_SUMMARY"
+
docsite-test:
- needs: [room, admission]
+ needs: [room, admission, heavy-ci]
if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft) && (github.event_name != 'workflow_dispatch' && !startsWith(github.base_ref, 'release/v') && !cancelled()) }}
# The Next.js production build uses every core it gets.
runs-on: ubuntu-latest
@@ -514,6 +559,14 @@ jobs:
echo "::error title=CI is full::CI is full: re-run all jobs or push later. Ten pull-request runs were already waiting for room."
exit 1
+ # An agent lane's push defers the heavy suites (spec:AST-030 FR20): the
+ # required check fails with the reason, never passes as skipped.
+ - name: Heavy CI deferred
+ if: needs.heavy-ci.outputs.deferred == 'true'
+ run: |
+ echo "::error::Heavy CI deferred: runs when marked ready and before merge (spec:AST-030 FR20)."
+ exit 1
+
- name: Check out the scope action
uses: actions/checkout@v7
with:
@@ -632,8 +685,8 @@ jobs:
# build-storybook + typecheck below.
test-ui:
name: test-ui (${{ matrix.shard }}/${{ strategy.job-total }})
- needs: [admission]
- if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (github.event_name != 'workflow_dispatch') }}
+ needs: [admission, heavy-ci]
+ if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && (needs.admission.result == 'success' && (github.event_name != 'workflow_dispatch'))) }}
# One runner ran the whole UI project in ~16 minutes and set the PR's wall
# time. Vitest's --shard gives each leg an equal share of the files; the
# two slowest files (~3.5 minutes each) bound a leg, so more legs stop
@@ -747,8 +800,8 @@ jobs:
test-node:
name: test-node (${{ matrix.shard }}/${{ strategy.job-total }})
- needs: [admission]
- if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (github.event_name != 'workflow_dispatch') }}
+ needs: [admission, heavy-ci]
+ if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && (needs.admission.result == 'success' && (github.event_name != 'workflow_dispatch'))) }}
# One runner ran the Node project in ~12 minutes. Vitest's --shard splits
# the files across the legs; `test` joins them.
strategy:
@@ -841,8 +894,8 @@ jobs:
# test-native-swift runs on macOS only then. It reads the same scope step as
# every test job; anything undecidable picks macOS.
native-swift-runner:
- needs: [admission]
- if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (github.event_name != 'workflow_dispatch') }}
+ needs: [admission, heavy-ci]
+ if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && (needs.admission.result == 'success' && (github.event_name != 'workflow_dispatch'))) }}
runs-on: ubuntu-slim
timeout-minutes: 5
permissions:
@@ -865,8 +918,8 @@ jobs:
paths: '^packages/native/.*(\.swift|/Package\.swift)$|^\.github/scripts/native-swift\.sh$|^\.github/actions/test-scope/'
test-native-swift:
- needs: [native-swift-runner]
- if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (github.event_name != 'workflow_dispatch' && always() && !cancelled()) }}
+ needs: [heavy-ci, native-swift-runner]
+ if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && (github.event_name != 'workflow_dispatch' && always() && !cancelled())) }}
runs-on: ${{ needs.native-swift-runner.outputs.applies == 'true' && 'macos-15' || 'ubuntu-slim' }}
timeout-minutes: 30
permissions:
@@ -962,6 +1015,7 @@ jobs:
needs:
[
room,
+ heavy-ci,
release-bump,
test-ui,
test-node,
@@ -990,6 +1044,30 @@ jobs:
echo "::error title=CI is full::CI is full: re-run all jobs or push later. Ten pull-request runs were already waiting for room."
exit 1
+ # The PR report says why the heavy checks did not run. Recorded here,
+ # in a job a failed-jobs re-run repeats, so its attempt has the record.
+ - name: Record the deferral for the PR report
+ if: needs.heavy-ci.outputs.deferred == 'true'
+ run: |
+ printf '{"headSha":"%s","runId":"%s","runAttempt":"%s"}\n' \
+ "${{ github.event.pull_request.head.sha }}" "$GITHUB_RUN_ID" "$GITHUB_RUN_ATTEMPT" > heavy-ci-deferred.json
+
+ - name: Upload the deferral for the PR report
+ if: needs.heavy-ci.outputs.deferred == 'true'
+ uses: actions/upload-artifact@v7
+ with:
+ name: heavy-ci-deferred-${{ github.run_attempt }}
+ path: heavy-ci-deferred.json
+ retention-days: 7
+
+ # An agent lane's push defers the heavy suites (spec:AST-030 FR20): the
+ # required check fails with the reason, never passes as skipped.
+ - name: Heavy CI deferred
+ if: needs.heavy-ci.outputs.deferred == 'true'
+ run: |
+ echo "::error::Heavy CI deferred: runs when marked ready and before merge (spec:AST-030 FR20)."
+ exit 1
+
- name: Check out the scope action
uses: actions/checkout@v7
with:
@@ -1035,8 +1113,8 @@ jobs:
# own terms. The decision script comes from the merge commit's trusted
# sparse checkout, and a lookup that fails denies the suite.
run-labels:
- needs: [admission]
- if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (github.event_name != 'workflow_dispatch' || inputs.operation == 'release-check') }}
+ needs: [admission, heavy-ci]
+ if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && (needs.admission.result == 'success' && (github.event_name != 'workflow_dispatch' || inputs.operation == 'release-check'))) }}
runs-on: ubuntu-slim
timeout-minutes: 5
permissions:
@@ -1072,8 +1150,8 @@ jobs:
# Starts once there is room for it, beside admission's wait for the rest of
# the run; every job that uses its build also needs admission, so the heavy
# legs still wait for room (spec:AST-030 FR16, DEC-16).
- needs: [room]
- if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && ((github.event_name != 'workflow_dispatch' || inputs.operation == 'release-check') && always() && !cancelled() && needs.room.outputs.full != 'true') }}
+ needs: [room, heavy-ci]
+ if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && ((github.event_name != 'workflow_dispatch' || inputs.operation == 'release-check') && always() && !cancelled() && needs.room.outputs.full != 'true')) }}
# Every browser lane waits for this job, and the package builds and the
# Storybook build run side by side (build-packages-and-storybook.mjs).
runs-on: ${{ (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check' && github.triggering_actor != 'github-actions[bot]') && '4-core-ubuntu' || 'ubuntu-latest' }}
@@ -1553,8 +1631,8 @@ jobs:
# gate passes. A skipped build-storybook job (a draft) skips this gate too;
# a fork pull request without `ci:run` still reports here.
build:
- needs: [room, build-storybook, typecheck]
- if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft) && (github.event_name != 'workflow_dispatch' && !cancelled() && (needs.build-storybook.result != 'skipped' || needs.room.outputs.full == 'true' || github.event_name == 'pull_request' && !(github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run')))) }}
+ needs: [room, heavy-ci, build-storybook, typecheck]
+ if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft) && (github.event_name != 'workflow_dispatch' && !cancelled() && (needs.build-storybook.result != 'skipped' || needs.room.outputs.full == 'true' || needs.heavy-ci.outputs.deferred == 'true' || github.event_name == 'pull_request' && !(github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run')))) }}
runs-on: ubuntu-slim
permissions: {}
steps:
@@ -1569,6 +1647,14 @@ jobs:
echo "::error title=CI is full::CI is full: re-run all jobs or push later. Ten pull-request runs were already waiting for room."
exit 1
+ # An agent lane's push defers the heavy suites (spec:AST-030 FR20): the
+ # required check fails with the reason, never passes as skipped.
+ - name: Heavy CI deferred
+ if: needs.heavy-ci.outputs.deferred == 'true'
+ run: |
+ echo "::error::Heavy CI deferred: runs when marked ready and before merge (spec:AST-030 FR20)."
+ exit 1
+
- name: Assert parallel builds succeeded
run: |
echo "build-storybook: ${{ needs.build-storybook.result }}"
@@ -1590,7 +1676,9 @@ jobs:
pr-a11y-shard:
name: pr-a11y (${{ matrix.shard }}/${{ strategy.job-total }})
needs: [admission, build-storybook]
- if: github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'
+ # A status check: heavy-ci, which skips on every run but an agent push,
+ # is an ancestor (spec:AST-030 FR20); its skip must not skip this job.
+ if: (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check') && !cancelled() && needs.admission.result == 'success' && needs.build-storybook.result == 'success'
strategy:
fail-fast: false
matrix:
@@ -1697,7 +1785,9 @@ jobs:
pr-a11y-guards:
name: pr-a11y (audit and guards)
needs: [build-storybook, run-labels]
- if: ((github.event_name == 'pull_request' && needs.run-labels.outputs.a11y == 'true') || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'))
+ # A status check: heavy-ci, which skips on every run but an agent push,
+ # is an ancestor (spec:AST-030 FR20); its skip must not skip this job.
+ if: (((github.event_name == 'pull_request' && needs.run-labels.outputs.a11y == 'true') || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'))) && !cancelled() && needs.build-storybook.result == 'success' && needs.run-labels.result == 'success'
runs-on: ${{ (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check' && github.triggering_actor != 'github-actions[bot]') && '2-core-ubuntu-arm' || 'ubuntu-24.04-arm' }}
timeout-minutes: ${{ github.event_name == 'workflow_dispatch' && 360 || 15 }}
permissions:
@@ -1828,7 +1918,9 @@ jobs:
pr-a11y-specs:
name: pr-a11y (browser specs)
needs: [build-storybook, run-labels]
- if: ((github.event_name == 'pull_request' && needs.run-labels.outputs.a11y == 'true') || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'))
+ # A status check: heavy-ci, which skips on every run but an agent push,
+ # is an ancestor (spec:AST-030 FR20); its skip must not skip this job.
+ if: (((github.event_name == 'pull_request' && needs.run-labels.outputs.a11y == 'true') || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'))) && !cancelled() && needs.build-storybook.result == 'success' && needs.run-labels.result == 'success'
runs-on: ${{ (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check' && github.triggering_actor != 'github-actions[bot]') && '2-core-ubuntu-arm' || 'ubuntu-24.04-arm' }}
timeout-minutes: ${{ github.event_name == 'workflow_dispatch' && 360 || 15 }}
permissions:
@@ -1941,7 +2033,9 @@ jobs:
a11y-contracts-shard:
name: Accessibility spec-test contracts (${{ matrix.shard }}/${{ strategy.job-total }})
needs: [admission, build-storybook]
- if: github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'
+ # A status check: heavy-ci, which skips on every run but an agent push,
+ # is an ancestor (spec:AST-030 FR20); its skip must not skip this job.
+ if: (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check') && !cancelled() && needs.admission.result == 'success' && needs.build-storybook.result == 'success'
# Six legs: at three, the slowest leg took ~20 minutes, held by its longest
# spec file; files longer than a leg's share are now cut across legs
# (spec:AST-030 FR23).
@@ -2051,8 +2145,8 @@ jobs:
delete-merged: true
pr-interaction:
- needs: [room, admission, build-storybook]
- if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (github.event_name != 'workflow_dispatch' && always() && !cancelled() && needs.room.outputs.full != 'true') }}
+ needs: [room, admission, heavy-ci, build-storybook]
+ if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && (github.event_name != 'workflow_dispatch' && always() && !cancelled() && needs.room.outputs.full != 'true')) }}
# Frame evidence measures timing: four cores, one Playwright worker.
runs-on: ubuntu-latest
timeout-minutes: 15
@@ -2169,8 +2263,8 @@ jobs:
# required context. Specs that need Chromium-only evidence skip themselves
# in WebKit.
pr-interaction-webkit:
- needs: [room, admission, build-storybook]
- if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (github.event_name != 'workflow_dispatch' && always() && !cancelled() && needs.room.outputs.full != 'true') }}
+ needs: [room, admission, heavy-ci, build-storybook]
+ if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && (github.event_name != 'workflow_dispatch' && always() && !cancelled() && needs.room.outputs.full != 'true')) }}
# Frame evidence measures timing: four cores, one Playwright worker.
runs-on: ubuntu-latest
timeout-minutes: 15
@@ -2304,8 +2398,8 @@ jobs:
# package ownership explicit; the historical `test` join above projects its
# result. Until runtime:build has a specialized route, broad CI dispatches it.
test-build:
- needs: [admission]
- if: (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (github.event_name != 'workflow_dispatch')
+ needs: [admission, heavy-ci]
+ if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && (needs.admission.result == 'success' && (github.event_name != 'workflow_dispatch'))) }}
runs-on: ubuntu-24.04-arm
timeout-minutes: 15
permissions:
@@ -2866,9 +2960,12 @@ jobs:
pr-rtl-shard:
name: pr-rtl (${{ matrix.package }}${{ matrix.parts > 1 && format(' {0}/{1}', matrix.part, matrix.parts) || '' }})
needs: [build-storybook, run-labels]
+ # A status check: heavy-ci, which skips on every run but an agent push,
+ # is an ancestor (spec:AST-030 FR20); its skip must not skip this job.
if: >-
((github.event_name == 'pull_request' && needs.run-labels.outputs.rtl == 'true') ||
- (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'))
+ (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check')) &&
+ !cancelled() && needs.build-storybook.result == 'success' && needs.run-labels.result == 'success'
# Core is the largest package, so its audit is split (`--shard`) and joined
# by pr-rtl-merge: three ways on a pull request, six on a release-check,
# where three legs took ~10 minutes (spec:AST-030 FR23). Every other
diff --git a/.github/workflows/pr-comment.yml b/.github/workflows/pr-comment.yml
index 3eed1a9a35..7ef340d2ee 100644
--- a/.github/workflows/pr-comment.yml
+++ b/.github/workflows/pr-comment.yml
@@ -435,6 +435,19 @@ jobs:
github-token: ${{ secrets.GITHUB_TOKEN }}
continue-on-error: true
+ # A failed run may be a deferred agent-lane push (spec:AST-030 FR20),
+ # whose report says so instead of an unavailable analysis.
+ - name: Download the heavy-CI deferral from the CI run
+ id: deferral-download
+ if: steps.identity.outputs.valid == 'true' && steps.identity.outputs.source_conclusion == 'failure'
+ uses: actions/download-artifact@v8
+ with:
+ name: heavy-ci-deferred-${{ steps.identity.outputs.run_attempt }}
+ path: heavy-ci-deferred
+ run-id: ${{ steps.identity.outputs.run_id }}
+ github-token: ${{ secrets.GITHUB_TOKEN }}
+ continue-on-error: true
+
- name: Cross-check artifact identity
id: cross-check
continue-on-error: true
@@ -554,6 +567,9 @@ jobs:
sourceRunAttempt: Number(process.env.RUN_ATTEMPT),
sourceConclusion: process.env.SOURCE_CONCLUSION,
},
+ fallbackMessage: require('node:fs').existsSync('heavy-ci-deferred/heavy-ci-deferred.json')
+ ? 'Heavy CI deferred: runs when marked ready and before merge. Lint, typecheck and any path-filtered checks ran on this push.'
+ : undefined,
visualFrames: {
imageBase: process.env.VISUAL_IMAGE_BASE,
published: process.env.VISUAL_PUBLISHED,
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f46c1cbe18..5cfd465f62 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -964,6 +964,12 @@ Storybook story for anything you added or altered.
request past either limit shows a failing check that says why, and runs in
full at its pre-merge re-run. Engineering owners listed in `.github/ENGOWNERS`
are not limited.
+- **Pull requests from the shared agent login run the heavy suites when ready
+ and before merge.** A push to a ready agent pull request runs lint and, in
+ the CI workflow, only typecheck (path-filtered workflows run as usual);
+ `test`, `build` and `docsite-test` fail with "Heavy CI deferred" (unless the
+ change is spec-only, which runs everything) until the pull request is marked ready or reopened, or its latest run is
+ re-run with **Re-run all jobs**, which runs everything at that head.
## Code Style
diff --git a/docs/specs/AST-030/spec.md b/docs/specs/AST-030/spec.md
index 8fa3abb221..c47399ac7e 100644
--- a/docs/specs/AST-030/spec.md
+++ b/docs/specs/AST-030/spec.md
@@ -403,6 +403,20 @@ they are separately named.
minutes added to time to green. A flag asks the reviewer to weigh the cost;
it fails no check.
+- **FR20 — An agent lane's push runs the fast checks; the heavy suites run when
+ it is ready and before merge.** A push to a ready pull request authored by the
+ shared agent login, into `main`, in its run's first attempt, runs only
+ typecheck in the CI workflow (lint keeps its own workflow), unless its trusted
+ classification is spec-only; the path-filtered workflows (FR14) are
+ unaffected. Its heavy jobs skip, and the required contexts `test`, `build` and `docsite-test` (FR7)
+ report failure with "Heavy CI deferred: runs when marked ready and before
+ merge", never success, so nothing merges on that run; the PR report says the
+ same. Marking the pull request ready, opening or reopening it, and any later
+ attempt of its run (the pre-merge re-run of all jobs) run every suite at that
+ head. A release merge-back, a release-branch pull request, every other
+ author, the review and spec gates (FR15) and the heavy-suite caps (FR16) are
+ unaffected (DEC-14).
+
- **FR21 — Main's full unit run is about hourly and always finishes.** The
Main workflow runs its unit suites (every Vitest project of every package,
never scoped to a change) only in a dispatched run, such as the one main's
@@ -518,6 +532,7 @@ The nightly perf lane is the one scheduled measurement outside them (FR18).
| FR17 | `ci-pr-gate.test.mjs` over every `pull_request` workflow and the shared conditions | branch here, fork with and without `ci:run`, another label, draft with the label, ready, push, merge group, dispatch | a job that can start on a pull request without the condition, a label trigger, a required job that skips for a pull request that may not run CI, or a draft or unlabelled fork that runs fails |
| FR18 | `perf-nightly-workflow.test.mjs`, `perf-trend.test.mjs` and `run-labels.test.mjs` | nightly and dispatch; labelled, unlabelled, draft and unvouched-fork pull requests; write, read and no access; newest label event; failed lookup; 10% boundary; metric floors; seven-day window edges; fewer than three runs; a metric over once, twice in a row, or a different metric before; recorded and pull request runs | a run on an unlabelled pull request, a label honoured from read access, a regression called at exactly 10%, under its floor or on one run alone, a run outside the window in the baseline, a pull request run that records, or a second regression issue fails |
| FR19 | `ci-impact.test.mjs`, `pr-preview.test.mjs` and the maintenance template | CI change and non-CI change; standard, non-standard and expression runners; added, removed and changed jobs; trigger change | a CI change reports no impact, a move onto a non-standard runner or a pool or time-to-green rise past its threshold goes unflagged, or the section names a price |
+| FR20 | `ci-heavy-deferral.test.mjs` over ci.yml, lint.yml and pr-comment.yml | agent push; marked ready; opened; reopened; re-run; another author; release branch; merge-back; spec-only change; a release-check and an opt-in label run, where the decision skips; a failed-jobs re-run of a deferred push | a heavy job runs on a deferred push, a required context passes or skips on one, a ready, reopened or re-run pull request defers, a spec-only change defers, the report hides the deferral, or a job below the decision skips because it skipped |
| FR21 | `ci-heavy-lanes.test.mjs` dispatch cases, `main-unit-run.test.mjs` over deploy.yml, `release-check-receipt.test.mjs` | push run; dispatched unit run; tip with the scheduler's or a person's release-check, or a person's maintenance capture; unit run cancelled, skipped or timed out; newer recheck or person's run of the tip; a person's validation of an older commit; cut commit with and without a passing unit run | a push runs the unit suites, a push cancels a unit run, a release-check comes without a unit run of its commit, an incomplete run goes unreported or waits a window, or a cut publishes without a passing unit run |
| FR22 | `main-validation-workflow.test.mjs` over the Main workflow and its commit resolver; `vitest-shard-sequencer.test.mjs` over the recorded Node times | six UI and six Node legs; dispatch without a commit, with a commit in main's history, with a commit outside it and with a malformed one; a re-check from the workflow token and from a person, and one that names `sha`; a `sha` before the size records, and one of only spaces; four and six Node legs over the recorded suite, a file with no recorded time, a project other than `node` | a hold, a leg past the fifteen-minute budget, a commit outside main's history that validates, a person's dispatch or a person's `sha` run that cancels or replaces a validation of main, a `sha` lane that checks out another commit, or a `sha` run named for main's tip, or two of the slowest Node files in one leg, a file run by no leg or by two, or a split that depends on collection order fails |
| FR23 | `release-check-shape.test.mjs`, `a11y-contract-shard.test.mjs` and the release-check workflow contract | release-check and pull-request legs; a contract file longer than a leg's share, one it cannot name exactly, and a serial one; the recorded suite; a re-check from an admin, a maintainer and a writer, from another branch, with a short SHA and with an older commit; failed-only beside a passed, a running and a missing run | a narrower release-check, a held or over-budget leg, a test selected by no leg or by two, a re-check that a writer can start, that waits for main's running check, or that re-runs jobs of another commit fails |
@@ -753,6 +768,24 @@ quiet, so the check would starve); holding a runner to wait out each push (it
is billed while it waits); a daily check (main's result would lag a whole
day).
+### DEC-14 — Agent lanes run the heavy suites when ready and before merge
+
+**Reference:** `spec:AST-030/DEC-14`
+**Decider:** `cixzhang`
+
+Most pull-request runs come from the shared agent login, and an agent pushes
+many times while it works; each push ran every heavy suite on a head that was
+replaced minutes later. The heavy suites now run at the two heads that decide
+a merge: the one that becomes ready and the one re-run before merge. Between
+them lint and typecheck give fast feedback. A deferred required context fails
+with its reason rather than passing as skipped, because a skipped required
+check counts as passing (FR17's rule), so a deferred head cannot merge.
+
+Rejected: leaving the required contexts pending (a commit status beside the
+job's check run of the same name is ambiguous to branch protection); deferring
+spec-only changes (their heavy jobs already do nothing, and every push would
+then need a re-run to merge).
+
### DEC-15 — Main's unit suites run about hourly, in full, to completion
**Reference:** `spec:AST-030/DEC-15`