CI explained

Français · Type: reference + troubleshooting · Audience: contributor · Context: engine repository · Status: ready · Applies from: 4.5.0

What GitHub Actions runs on the engine repository, why a job ran or said "not needed by the plan", and what to do when one is red. The workflows are in .github/workflows/; the plan that decides what a pull request runs is tools/ci-plan.ts. Which test suite runs in which job is Which tests run when.

The workflows

The three tiers of ci

feature since 4.1.9

The fast tier, on every change. plan reads the diff; check and coverage run beside it:

• check: on a pull request, changes -- --check (the fragment, Conventions) and field:carry -- --check-range (no carried pass changes its trust root); then quality (format, lint, knip, both TypeScript configurations, content lint), docs:truth, ffmpeg, build:game (the sample game's gates, the bundle, verify:dist, the spoiler check, the asset audit), weight -- --release, quality:baseline -- --check --dist, prove:game, audit:deps when package.json or the lockfile moved, then the two-entry build (game and Studio demo) that the e2e rows play, kept as the dist artifact; on main it also assembles Pages' /docs/ from the released documentation archives.
• coverage: the unit suite once, under V8 coverage (test:coverage), then the coverage ratchet: a warning on a pull request, a failure on main and on a tag (The coverage ratchet).

The second tier, what the change can break. Each job needs plan (most also check) and reads its gate in the plan: it runs its real work, or one step that says "not needed by the plan" and succeeds.

The third tier, off the pull request path: the mutation sets on a pull request labelled full-ci, the nightly, the candidate and the release.

pr-gate reads every job's result: each must be success; the mutation jobs may be skipped where they do not run. It is the one check that sums a pull request up.

pages, on main only, after a green pr-gate: deploys the game, the Studio demo and /docs/ to GitHub Pages.

The plan (npm run ci:plan)

feature since 4.1.9

# in the engine repository, on your branch
npm run ci:plan                    # against origin/main
npm run ci:plan -- --base=<ref>
npm run ci:plan -- --files=src/engine/dom/room.ts,games/demo/rooms/garden.ts

It prints, on stderr, one line per changed file with the rule that matched and the gates it opened, then the plan; on stdout, one line of JSON ({"auditDeps":…,"node24":…,…,"all":…,"docs":…,"docsPages":[…],"pagesOnly":…}), which the plan job writes to its output. The first rule that matches a path wins, and a change runs the union of what its files ask:

A git error runs everything too: the plan never decides that it does not need to be checked. docs is true when the change touches the documentation, its generators, or a file a wiki page rests on (a sources glob of wiki/manifest.json); docsPages names those pages, to reread. It opens no job: the fast tier runs the doc tests on every change.

Everything on a pull request: the full-ci label

On main, on a tag and on a pull request labelled full-ci, the plan is --all: every gate opens. The label also starts the mutation jobs of ci and a candidate run for information. Add the label, then push (the label applies to the next run).

pages-only runs

Applies from 4.5.0 · feature since 4.5.0

docs-publish ends by gh workflow run ci.yml --ref main -f pages-only=true. The plan is then --pages-only: no gate opens, and check, coverage and cross-runtime skip everything but the Pages build, /docs/ and the upload. A dispatched run cancels no running run: it waits. GitHub keeps one pending run per concurrency group whatever cancel-in-progress says, so a dispatch queued while a push's run on main is pending replaces it (that commit is then deployed by the dispatch without its own checks), and a later push replaces a pending dispatch.

Limit · pages-fail-closed If /docs/ cannot be assembled from the released archives (a network failure, an archive refused), the check job fails on main and Pages is not deployed: never a site without /docs/ nor with an unchecked one. A rerun of the job is the recovery.

A job failed on my pull request

1. Read the plan's summary in the plan job (or run npm run ci:plan locally): it says why each job ran.

2. Reproduce locally, in the engine repository, with the job's own command:

   Red job	Run locally
   check	the failing step: npm run quality, npm run docs:truth, npm run build:game, npm run quality:baseline -- --check --dist (after npm run build:web), npm run prove:game, npm run changes -- --check
   coverage	npm run test:coverage (a test, or a floor of vite.config.ts not met)
   node-24	npm run test:node under Node 24
   e2e, reference, second-game	npm run build:game, npm run preview -- --port 5173 &, then the row's npm run e2e -- http://127.0.0.1:5173/ --game demo --prod … (E2E_BROWSER=webkit for a WebKit row)
   fresh-install, external-consumer, upgrade	npm run fresh-install, npm run external-consumer, npm run upgrade-check -- --from=previous
   mutation (<set>)	npm run test:mutation:core -- --set=<set> (Mutation testing)

   A failed e2e row uploads its screenshots as an artifact: read them first.

3. Check the known flakes below before rerunning. A rerun of a red job that is not a known flake hides a bug.

4. Fix, push, read pr-gate again.

Known flakes and their handling

Limit · windows-not-required The windows job runs the unit suite without the files that assume POSIX; it is not a required check of the ruleset until the maintainer adds it.

Related identifiers

• npm run ci:plan, the full-ci label, pr-gate, the pages-only input.
• Which tests run when, Before a pull request, Releasing, Mutation testing.

Edit the source of this page · Report an error