Le problème
Prenons une boutique en ligne en monorepo : les
services Symfony order, stock et
shipping, le front Vue shop et le
package PHP app-contracts. moon décide quoi
lancer à chaque pull request, comme dans
notre article sur les pipelines minces. Mais chaque projet déclare ses tâches dans son
moon.yml, et elles divergent.
Des noms différents pour le même geste.
PHPStan s'appelle phpstan dans
order et analyse dans
stock. Les tests de
shop s'appellent test, ceux de
shipping test-phpunit. Pour tester
un projet, un nouveau venu lit son moon.yml, et
un agent de code devine.
Une CI qui connaît les stacks. Un workflow
vérifie les services Symfony, un autre les fronts, chacun
avec ses étapes et son check obligatoire.
app-contracts n'entre dans aucun des
deux : son style n'est vérifié nulle part.
Des entrées trop étroites. Les tâches de
order n'ont pour entrées que les fichiers de
order. Une pull request qui ne touche que
app-contracts ne relance ni PHPStan ni les
tests des services qui l'utilisent.
Les options
Des tâches déclarées projet par projet
- Ce qu'elles règlent : chaque projet est autonome, sa configuration tient dans un fichier.
- Ce qu'elles coûtent : la même tâche copiée puis modifiée. Rien n'empêche deux noms pour le même geste.
Une convention écrite, appliquée par des scripts
-
Ce qu'elle règle : un document fixe
les noms, que chaque projet implémente en scripts Composer
ou
package.json. - Ce qu'elle coûte : rien ne la vérifie, et elle dérive au premier projet ajouté dans l'urgence.
Un workflow de CI par stack
- Ce qu'il règle : chaque stack a ses étapes et ses journaux.
- Ce qu'il coûte : une logique hors de portée d'un poste de développement, et un workflow de plus par stack.
Des tâches héritées, par condition
moon lit les fichiers de .moon/tasks/. Chacun
déclare des tâches, et les conditions
(inheritedBy) qu'un projet doit remplir pour en
hériter.
- Ce qu'elles règlent : une tâche s'écrit une fois par stack, et les noms sont identiques par construction.
- Ce qu'elles coûtent : une tâche se lit dans plusieurs fichiers, et l'ordre de leur fusion compte.
Notre recommandation
Une interface de tâches unique, implémentée une fois par
stack dans .moon/tasks/, et un seul workflow
qui ne connaît que ces noms.
| Tâche | shop (Vue) |
order, stock,
shipping (Symfony)
|
app-contracts |
|---|---|---|---|
lint |
ESLint, après vue-tsc | PHPStan | |
format, format-fix |
Prettier | PHP-CS-Fixer | PHP-CS-Fixer |
audit |
yarn npm audit |
composer audit |
|
test |
Vitest | PHPUnit | |
build |
Vite | ||
docker-build |
image du front | image de production |
Une case vide est une tâche que le projet ne définit pas.
moon ci :build lance build dans
chaque projet affecté qui la définit, et ignore les autres.
Le workflow ignore donc les stacks et les projets.
Nous regroupons sous lint ce que
notre article sur la qualité de code Symfony
sépare en lint et analyse. Le
style passe dans format, comme pour le front.
Le même nom donne le même geste partout :
moon run order:test et
moon run shop:test lancent les tests, quel que
soit l'outil. moon project order liste les
tâches d'un projet, et
moon task order:lint affiche la commande
fusionnée et les fichiers dont elle hérite. Un nouveau venu
ou un agent de code vérifie son travail sans lire de
documentation.
Les compromis assumés
Une tâche répartie entre plusieurs fichiers.
La commande de docker-build vient d'un fichier,
sa cible d'un autre. moon task montre le
résultat fusionné : c'est lui que nous relisons en
revue.
Docker obligatoire pour les projets PHP.
Les outils PHP tournent dans des conteneurs, jamais sur
l'hôte. Le hook de pre-commit écarte donc les projets PHP
(--query 'language!=php'), car un commit ne
doit pas exiger Docker. L'éditeur formate le PHP à
l'enregistrement, et la CI rattrape le reste.
Plus de tâches relancées. Toute
modification de app-contracts relance toutes
les tâches des services, format compris. Nous préférons du
temps de runner à une vérification oubliée.
Une quality gate sans tolérance. Un job
sauté ou désactivé fait échouer la gate. Pour désactiver un
job, on le retire aussi des needs de la gate.
Le signal qui doit faire réexaminer ce choix : des exceptions qui se multiplient. Quand plusieurs
projets excluent ou renomment des tâches héritées
(workspace.inheritedTasks), l'interface ne
décrit plus leur réalité.
Mise en œuvre
Les exemples utilisent moon 2.6 et GitHub Actions. Les services Symfony 7.4 tournent sur PHP 8.4, en local dans leur stack Docker Compose.
1. Déclarer la stack de chaque projet
L'héritage repose sur ce que déclare chaque
moon.yml, langage compris : un langage
détecté ne compte pas.
# services/order/moon.yml
language: php
layer: application
stack: backend
tags: [symfony, docker]
dependsOn:
- app-contracts
Le front shop (fronts/shop)
déclare language: typescript,
stack: frontend et le tag docker.
app-contracts déclare
language: php et layer: library,
sans tag : il n'hérite que du formatage. Aucun de ces
fichiers ne déclare de tâche.
2. Un fichier par stack, des conditions combinées
Plusieurs conditions se combinent en ET, plusieurs valeurs
d'une condition en OU, et les tags acceptent les clauses
and, or et not. Une
tâche définie dans plusieurs fichiers est fusionnée :
par défaut, args, deps et
inputs s'ajoutent à la suite.
3. Formater le PHP sans PHP sur l'hôte
Une seule configuration de PHP-CS-Fixer, à la racine, couvre tous les projets PHP. L'outil tourne depuis son image officielle, par un script qu'appellent la tâche moon et l'éditeur.
#!/usr/bin/env bash
# tools/php-cs-fixer.sh
set -euo pipefail
# Version unique ; son PHP suit celui des services, car son analyseur lexical lit leur code.
image='ghcr.io/php-cs-fixer/php-cs-fixer:3.95.27-php8.4'
root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
# Le dépôt est monté à son propre chemin : les chemins passés gardent leur sens.
mounts=(--volume "$root:$root")
# L'éditeur formate une copie temporaire, hors du dépôt : on monte son dossier.
for arg in "$@"; do
path="${arg#--*=}"
if [[ "$path" == /* && -e "$path" && "$path" != "$root"/* ]]; then
[[ -d "$path" ]] || path="$(dirname "$path")"
mounts+=(--volume "$path:$path")
fi
done
exec docker run --rm --user "$(id -u):$(id -g)" --network none \
"${mounts[@]}" --workdir "$PWD" "$image" "$@"
# .moon/tasks/php.yml
inheritedBy:
language: php
tasks:
format:
command: $workspaceRoot/tools/php-cs-fixer.sh
args:
[check, --config=$workspaceRoot/.php-cs-fixer.dist.php, --path-mode=intersection, --diff, .]
inputs: &php-cs-fixer-inputs
- '**/*.php'
- /.php-cs-fixer.dist.php
- /tools/php-cs-fixer.sh
format-fix:
command: $workspaceRoot/tools/php-cs-fixer.sh
args: [fix, --config=$workspaceRoot/.php-cs-fixer.dist.php, --path-mode=intersection, .]
inputs: *php-cs-fixer-inputs
options:
# Ses corrections modifient ses entrées : un cache ne les rejouerait pas.
cache: false
--path-mode=intersection croise le
. de la commande, la racine du projet, avec le
finder de la configuration : chaque projet vérifie ses
seuls fichiers. Le script et la configuration sont des
entrées : changer de version relance la vérification
partout.
// .php-cs-fixer.dist.php (racine du monorepo)
$finder = (new PhpCsFixer\Finder())
->in([__DIR__.'/app-contracts', __DIR__.'/services'])
// Par nom, à toute profondeur, comme vendor/ par défaut.
->exclude(['var'])
// Le coffre de secrets de chaque service.
->notPath('#/config/secrets/#');
return (new PhpCsFixer\Config())
->setRules(['@Symfony' => true])
->setFinder($finder);
Le finder liste ses exclusions au lieu d'appeler
ignoreVCSIgnored(true), pour deux raisons.
Cette option lit les .gitignore, pas l'index de
git : un fichier suivi malgré une règle (git add -f) échappe à la vérification.
De plus, jusqu'au 29 septembre 2026, Symfony Finder ne
trouvait la racine du dépôt que si .git était
un dossier. Dans un worktree, .git est un
fichier : le .gitignore racine était
ignoré, et la sélection différait de la CI. Le correctif est
publié dans Symfony 6.4.47, 7.4.20 et 8.1.8 ; l'image
3.95.27, construite avant, garde l'ancien comportement.
4. Les services Symfony : le local d'abord, la CI en plus
symfony.yml décrit les tâches telles qu'elles
tournent sur un poste, dans le conteneur du service, sans
rien savoir de la CI.
# .moon/tasks/symfony.yml
inheritedBy:
tag: symfony
# Vaut pour toutes les tâches héritées du service, format et docker-build compris.
implicitInputs:
- project://^
tasks:
install:
command: docker compose run --rm php composer install --no-interaction
inputs: [composer.json, composer.lock]
options:
internal: true
lint:
command: docker compose run --rm php vendor/bin/phpstan analyse --no-progress
deps: [install]
test:
command: docker compose run --rm php vendor/bin/phpunit
deps: [install]
audit:
command: docker run --rm --volume $projectRoot:/app composer:2.10 audit --locked --abandoned=report
inputs: [composer.json, composer.lock]
options:
cache: false
project://^ désigne tous les projets du
dependsOn : une modification de
app-contracts rend affectées les tâches des
services. L'audit passe par l'image officielle de
Composer : avec --locked, il ne lit que
composer.json et composer.lock,
sans vendor/.
--abandoned=report signale les paquets
abandonnés sans faire échouer la tâche.
ci.yml ajoute ce qu'un runner n'a pas, sous les
mêmes ids de tâches, avec la même condition :
# .moon/tasks/ci.yml
inheritedBy:
tag: symfony
tasks:
ci-test-image:
# Le nom d'image qu'attend compose.yml, sources et vendor/ compris.
command: docker buildx build --target test --load --tag app/$project:test .
options:
cache: false
internal: true
runInCI: only
install:
# vendor/ est déjà dans l'image de test.
options:
runInCI: skip
lint:
deps: [ci-test-image]
test:
deps: [ci-test-image]
runInCI: only lance une tâche en CI
seulement : sur un poste, ci-test-image ne
tourne pas. skip fait l'inverse, tout en
gardant la relation valide : moon refuse qu'une tâche
lancée en CI dépende d'une tâche à
runInCI: false. En CI, le workflow fixe
COMPOSE_FILE=compose.yml : sans l'override
de développement, php tourne sur l'image de
test.
Les options sont écrites tâche par tâche : c'est le
piège de ces fichiers. Un taskOptions, comme
implicitInputs ou implicitDeps,
vaut pour toutes les tâches héritées du projet, pas
seulement pour celles du fichier. Un
taskOptions: { runInCI: only } en tête de
ci.yml réserverait à la CI toutes les tâches du
service.
5. L'ordre de fusion, explicite
Sans order, moon fusionne les fichiers par
poids croissant. Le poids additionne 50 pour une toolchain
ou un langage, 100 pour une stack, 150 pour une couche et
500 pour des tags. À égalité, moon trie par nom de fichier.
Le champ order n'est pas dans la documentation,
mais figure dans le schéma de configuration de moon 2.
# .moon/tasks/docker-php.yml
inheritedBy:
tags:
and: [docker, symfony]
# Après docker.yml (500) : ces arguments suivent sa commande.
order: 600
tasks:
docker-build:
args: [--target, frankenphp_prod]
docker.yml définit la commande,
docker buildx build --tag app/$project:ci .,
avec le tag docker pour condition. Les deux
fichiers pèsent 500, et docker-php.yml passe
avant docker.yml : le tiret se classe
avant le point. Sans order, la commande
deviendrait
docker --target frankenphp_prod buildx build ..., que Docker refuse.
docker-node.yml ajoute
deps: [build] au même
docker-build, et son calcul donne déjà 600 (tag
et stack). Nous l'écrivons pourtant : l'ordre ne doit
pas dépendre d'une condition ajoutée plus tard.
6. Un audit jamais mis en cache
# .moon/tasks/node.yml (extrait)
inheritedBy:
language: typescript
stack: frontend
tasks:
lint:
command: eslint --no-error-on-unmatched-pattern .
deps: [typecheck]
audit:
command: yarn npm audit --recursive --no-deprecations
inputs: [package.json, /yarn.lock, /.yarnrc.yml]
options:
cache: false
Une advisory se publie sans qu'aucune entrée ne
change : avec le cache, moon rejouerait un ancien
succès. cache: false ne décide pas quand
l'audit tourne : runInCI: always le
lancerait sur chaque pull request, même sans projet affecté.
Nous gardons les projets affectés, plus un passage planifié
sur la branche principale.
7. Un workflow, une quality gate
# .github/workflows/qg.yml
name: qg
on:
pull_request:
permissions:
contents: read
env:
COMPOSE_FILE: compose.yml
jobs:
checks:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
tasks: [':lint', ':format', ':audit', ':test', ':build :docker-build']
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
fetch-depth: 0
- uses: moonrepo/setup-toolchain@261c62cb5b0f580c7be7c8cd0f023a2e96756095 # v0.6.4
with:
auto-install: true
- uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
- run: moon ci ${{ matrix.tasks }}
quality-gate:
needs: [checks]
if: always()
runs-on: ubuntu-latest
steps:
- if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') || contains(needs.*.result, 'skipped')
run: exit 1
Sans filtre de chemins, le workflow tourne sur chaque pull
request : un check obligatoire jamais déclenché reste
en attente et bloque la fusion. Sans projet affecté,
moon ci ne lance rien et réussit.
Chaque job de la matrice lance moon ci, ce que
notre article sur les pipelines
déconseille : sur main, chaque job
calculerait sa propre base. Ce workflow ne tourne que sur
pull_request, où tous les jobs lisent la même
base, la branche cible.
quality-gate est le seul check
obligatoire : le nom d'un job de matrice change avec
ses valeurs. Pour GitHub, un job sauté par une condition
compte comme un succès. Notre article sur les pipelines
l'accepte, car son job d'images saute quand rien n'est à
construire.
Ici, checks n'a pas de condition : un
skipped ne peut venir que d'un job désactivé,
et la gate échoue.
Checklist
- Les mêmes noms de tâches pour chaque stack.
-
language,stack,layeret tags déclarés dans chaquemoon.yml. -
Un fichier
.moon/tasks/par stack, et unorderexplicite quand la fusion en dépend. -
Des tâches locales, complétées par un fichier CI à
runInCI: only. - Aucune option de fichier qui ne doive valoir pour toutes les tâches.
-
project://^en entrée des tâches qui utilisent un package interne. -
Un
auditsans cache. - Une configuration PHP-CS-Fixer unique, lancée depuis son image.
-
Un seul check obligatoire, en échec dès qu'un job n'est
pas
success.
Sources
Versions relevées le 15 novembre 2026 : moon 2.6.5, PHP-CS-Fixer 3.95.30, Composer 2.11.2 ; actions/checkout 7.0.1, moonrepo/setup-toolchain 0.6.4 et docker/setup-buildx-action 4.4.1.
-
moon,
héritage des tâches : conditions
inheritedBy, clauses et stratégies de fusion. -
moon,
.moon/tasks :
implicitInputs,implicitDepsettaskOptions. -
moon,
schéma v2 des fichiers de tâches
(
inheritedBy.order) ; poids par défaut et tri par nom dans inherited_tasks_config.rs et inherited_tasks_manager.rs. -
moon,
configuration de projet :
language,args,cache,runInCI, entréesproject://. - moon, commandes ci, project et task ; cibles, tokens et langage de requête.
-
PHP-CS-Fixer,
installation
(image Docker),
usage
(
--path-mode) et Finder. -
Symfony,
composant Finder
(
ignoreVCSIgnored) et correctif pour un fichier .git. -
Git,
git-worktree
(le fichier
.gitd'un worktree) et gitignore (fichiers déjà suivis). - vscode-php-cs-fixer : formatage d'une copie temporaire.
-
Composer,
commande audit
(
--locked,--abandoned) et image officielle ; Yarn, yarn npm audit. - Docker Compose, fusion des fichiers et COMPOSE_FILE.
- GitHub, contexte needs et Troubleshooting required status checks.
- Lychen, pull requests 245, 246, 247 et 250 : une mise en œuvre open source de cette interface de tâches et de sa quality gate, dans un monorepo moon.