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.

Une tâche écrite une fois par stack : chaque projet expose les mêmes noms Fichier de .moon/tasks/ et condition order, stock, shipping app-contracts shop php.yml language: php symfony.yml tag: symfony ci.yml tag: symfony (ajouts pour la CI) node.yml language: typescript ET stack: frontend docker.yml tag: docker docker-php.yml tags: docker ET symfony, order: 600 docker-node.yml tag: docker ET stack: frontend, order: 600 fusion : par order, puis par nom de fichier En sortie : les mêmes noms de tâches, quelle que soit la stack order, stock, shipping lint format format-fix audit test docker-build shop lint format format-fix audit test build docker-build app-contracts format format-fix

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, layer et tags déclarés dans chaque moon.yml.
  • Un fichier .moon/tasks/ par stack, et un order explicite 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 audit sans 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.