La CI expliquée

English · Type : référence + dépannage · Public : contributeur · Contexte : dépôt du moteur · Statut : prête · S'applique depuis : 4.5.0

Ce que GitHub Actions lance sur le dépôt du moteur, pourquoi un job a tourné ou a dit « not needed by the plan », et que faire quand l'un d'eux est rouge. Les workflows sont dans .github/workflows/ ; le plan qui décide de ce que lance une pull request est tools/ci-plan.ts. Quelle suite de tests tourne dans quel job, c'est Quels tests tournent quand.

Les workflows

Les trois paliers de ci

fonction apparue en 4.1.9

Le palier rapide, à chaque changement. plan lit le diff ; check et coverage tournent à côté :

• check : sur une pull request, changes -- --check (le fragment, Conventions) et field:carry -- --check-range (aucune passe reportée ne change sa racine de confiance) ; puis quality (formatage, lint, knip, les deux configurations TypeScript, lint de contenu), docs:truth, ffmpeg, build:game (les barrières du jeu d'exemple, le bundle, verify:dist, la vérification des spoilers, l'audit des assets), weight -- --release, quality:baseline -- --check --dist, prove:game, audit:deps quand package.json ou le fichier de verrouillage a bougé, puis le build à deux entrées (jeu et démo du Studio) que jouent les lignes e2e, gardé comme artefact dist ; sur main, il assemble aussi le /docs/ de Pages à partir des archives de documentation publiées.
• coverage : la suite unitaire une fois, sous couverture V8 (test:coverage), puis le cliquet de couverture : un avertissement sur une pull request, un échec sur main et sur un tag (Le cliquet de couverture).

Le deuxième palier, ce que le changement peut casser. Chaque job a besoin de plan (la plupart aussi de check) et lit sa barrière dans le plan : il fait son vrai travail, ou une seule étape qui dit « not needed by the plan » et réussit.

Le troisième palier, hors du chemin de la pull request : les ensembles de mutation sur une pull request étiquetée full-ci, la nightly, le candidat et la release.

pr-gate lit le résultat de chaque job : chacun doit être success ; les jobs de mutation peuvent être skipped là où ils ne tournent pas. C'est la seule vérification qui résume une pull request.

pages, sur main seulement, après un pr-gate vert : déploie le jeu, la démo du Studio et /docs/ sur GitHub Pages.

Le plan (npm run ci:plan)

fonction apparue en 4.1.9

# dans le dépôt du moteur, sur votre branche
npm run ci:plan                    # contre origin/main
npm run ci:plan -- --base=<ref>
npm run ci:plan -- --files=src/engine/dom/room.ts,games/demo/rooms/garden.ts

Il affiche, sur la sortie d'erreur, une ligne par fichier changé avec la règle qui l'a pris et les barrières qu'il ouvre, puis le plan ; sur la sortie standard, une ligne de JSON ({"auditDeps":…,"node24":…,…,"all":…,"docs":…,"docsPages":[…],"pagesOnly":…}), que le job plan écrit dans sa sortie. La première règle qui correspond à un chemin l'emporte, et un changement lance l'union de ce que demandent ses fichiers :

Une erreur de git lance tout aussi : le plan ne décide jamais qu'il n'a pas besoin d'être vérifié. docs est vrai quand le changement touche la documentation, ses générateurs, ou un fichier sur lequel repose une page du wiki (un motif sources de wiki/manifest.json) ; docsPages nomme ces pages, à relire. Il n'ouvre aucun job : le palier rapide lance les tests de documentation à chaque changement.

Tout sur une pull request : l'étiquette full-ci

Sur main, sur un tag et sur une pull request étiquetée full-ci, le plan est --all : toutes les barrières s'ouvrent. L'étiquette lance aussi les jobs de mutation de ci et un run de candidate pour information. Ajoutez l'étiquette, puis poussez (elle s'applique au run suivant).

Les runs pages-only

S'applique depuis la 4.5.0 · fonction apparue en 4.5.0

docs-publish se termine par gh workflow run ci.yml --ref main -f pages-only=true. Le plan est alors --pages-only : aucune barrière ne s'ouvre, et check, coverage et cross-runtime sautent tout sauf le build de Pages, /docs/ et le téléversement. Un run déclenché à la main n'annule aucun run en cours : il attend. GitHub garde un seul run en attente par groupe de concurrence quoi que dise cancel-in-progress : un déclenchement mis en file pendant qu'un run de push sur main attend le remplace (ce commit est alors déployé par le déclenchement sans ses propres vérifications), et un push ultérieur remplace un déclenchement en attente.

Limite · pages-fail-closed Si /docs/ ne peut pas être assemblé depuis les archives publiées (une panne réseau, une archive refusée), le job check échoue sur main et Pages n'est pas déployé : jamais un site sans /docs/ ni avec un /docs/ non vérifié. Relancer le job est la reprise.

Un job a échoué sur ma pull request

1. Lisez le résumé du plan dans le job plan (ou lancez npm run ci:plan en local) : il dit pourquoi chaque job a tourné.

2. Reproduisez en local, dans le dépôt du moteur, avec la commande du job :

   Job rouge	En local
   check	l'étape qui échoue : npm run quality, npm run docs:truth, npm run build:game, npm run quality:baseline -- --check --dist (après npm run build:web), npm run prove:game, npm run changes -- --check
   coverage	npm run test:coverage (un test, ou un seuil de vite.config.ts non atteint)
   node-24	npm run test:node sous Node 24
   e2e, reference, second-game	npm run build:game, npm run preview -- --port 5173 &, puis la commande de la ligne npm run e2e -- http://127.0.0.1:5173/ --game demo --prod … (E2E_BROWSER=webkit pour une ligne WebKit)
   fresh-install, external-consumer, upgrade	npm run fresh-install, npm run external-consumer, npm run upgrade-check -- --from=previous
   mutation (<ensemble>)	npm run test:mutation:core -- --set=<ensemble> (Tests de mutation)

   Une ligne e2e qui échoue téléverse ses captures en artefact : lisez-les d'abord.

3. Regardez les instabilités connues ci-dessous avant de relancer. Relancer un job rouge qui n'est pas une instabilité connue cache un bug.

4. Corrigez, poussez, relisez pr-gate.

Instabilités connues et leur traitement

Limite · windows-not-required Le job windows lance la suite unitaire sans les fichiers qui supposent POSIX ; ce n'est pas une vérification exigée par les règles du dépôt tant que le mainteneur ne l'y ajoute pas.

Identifiants liés

• npm run ci:plan, l'étiquette full-ci, pr-gate, l'entrée pages-only.
• Quels tests tournent quand, Avant une pull request, Publier une release, Tests de mutation.

Modifier la source de cette page · Signaler une erreur