The problem

Take an online shop in a monorepo: the Symfony services order, stock and shipping, the Vue front shop and the PHP package app-contracts. moon decides what to run on each pull request, as in our article on thin pipelines. But each project declares its tasks in its own moon.yml, and they drift apart.

Different names for the same action. PHPStan is called phpstan in order and analyse in stock. The tests of shop are called test, those of shipping test-phpunit. To test a project, a newcomer reads its moon.yml, and a coding agent guesses.

A CI that knows the stacks. One workflow checks the Symfony services, another the fronts, each with its own steps and required check. app-contracts fits in neither: its style is checked nowhere.

Inputs that are too narrow. The tasks of order only have the files of order as inputs. A pull request that only touches app-contracts reruns neither PHPStan nor the tests of the services that use it.

The options

Tasks declared project by project

  • What they solve: each project is self-contained, its configuration fits in one file.
  • What they cost: the same task copied then modified. Nothing prevents two names for the same action.

A written convention, applied through scripts

  • What it solves: a document sets the names, which each project implements as Composer or package.json scripts.
  • What it costs: nothing checks it, and it drifts with the first project added in a hurry.

One CI workflow per stack

  • What it solves: each stack has its own steps and logs.
  • What it costs: logic out of reach of a developer machine, and one more workflow per stack.

Inherited tasks, by condition

moon reads the files in .moon/tasks/. Each one declares tasks, and the conditions (inheritedBy) a project must meet to inherit them.

  • What they solve: a task is written once per stack, and the names are identical by construction.
  • What they cost: a task is read across several files, and the order in which they merge matters.

Our recommendation

A single task interface, implemented once per stack in .moon/tasks/, and a single workflow that only knows these names.

Task shop (Vue) order, stock, shipping (Symfony) app-contracts
lint ESLint, after 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 the front's image production image

An empty cell is a task the project does not define. moon ci :build runs build in every affected project that defines it, and ignores the others. The workflow therefore ignores stacks and projects.

We group under lint what our article on Symfony code quality splits into lint and analyse. Style moves to format, as for the front.

The same name means the same action everywhere: moon run order:test and moon run shop:test run the tests, whatever the tool. moon project order lists a project's tasks, and moon task order:lint shows the merged command and the files it inherits from. A newcomer or a coding agent checks their work without reading any documentation.

A task written once per stack: every project exposes the same names File in .moon/tasks/ and condition order, stock, shipping app-contracts shop php.yml language: php symfony.yml tag: symfony ci.yml tag: symfony (CI additions) node.yml language: typescript AND stack: frontend docker.yml tag: docker docker-php.yml tags: docker AND symfony, order: 600 docker-node.yml tag: docker AND stack: frontend, order: 600 merge: by order, then by file name Output: the same task names, whatever the 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

The trade-offs we accept

A task spread over several files. The command of docker-build comes from one file, its target from another. moon task shows the merged result: that is what we read in review.

Docker required for the PHP projects. The PHP tools run in containers, never on the host. The pre-commit hook therefore leaves the PHP projects out (--query 'language!=php'), because a commit must not require Docker. The editor formats PHP on save, and the CI catches the rest.

More tasks rerun. Any change to app-contracts reruns every task of the services, format included. We prefer runner time to a forgotten check.

A quality gate without tolerance. A skipped or disabled job fails the gate. To disable a job, you also remove it from the gate's needs.

The signal that should make us reconsider: exceptions that pile up. When several projects exclude or rename inherited tasks (workspace.inheritedTasks), the interface no longer describes what they do.

Implementation

The examples use moon 2.6 and GitHub Actions. The Symfony 7.4 services run on PHP 8.4, locally in their Docker Compose stack.

1. Declare each project's stack

Inheritance relies on what each moon.yml declares, language included: a detected language does not count.

# services/order/moon.yml
language: php
layer: application
stack: backend
tags: [symfony, docker]
dependsOn:
  - app-contracts

The shop front (fronts/shop) declares language: typescript, stack: frontend and the docker tag. app-contracts declares language: php and layer: library, with no tag: it only inherits the formatting. None of these files declares a task.

2. One file per stack, combined conditions

Several conditions combine with AND, several values of one condition with OR, and tags accept the and, or and not clauses. A task defined in several files is merged: by default, args, deps and inputs are appended.

3. Format PHP without PHP on the host

A single PHP-CS-Fixer configuration, at the root, covers every PHP project. The tool runs from its official image, through a script called by the moon task and the editor.

#!/usr/bin/env bash
# tools/php-cs-fixer.sh
set -euo pipefail

# One version; its PHP follows the services' one, as its lexer reads their code.
image='ghcr.io/php-cs-fixer/php-cs-fixer:3.95.27-php8.4'
root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"

# The repository is mounted at its own path: the paths passed keep their meaning.
mounts=(--volume "$root:$root")
# The editor formats a temporary copy, outside the repository: mount its folder.
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:
      # Its fixes edit its own inputs: a cache could not replay them.
      cache: false

--path-mode=intersection intersects the command's ., the project root, with the configuration's finder: each project checks its own files only. The script and the configuration are inputs: changing the version reruns the check everywhere.

// .php-cs-fixer.dist.php (monorepo root)
$finder = (new PhpCsFixer\Finder())
    ->in([__DIR__.'/app-contracts', __DIR__.'/services'])
    // By name, at any depth, as vendor/ is by default.
    ->exclude(['var'])
    // Each service's secrets vault.
    ->notPath('#/config/secrets/#');

return (new PhpCsFixer\Config())
    ->setRules(['@Symfony' => true])
    ->setFinder($finder);

The finder lists its exclusions instead of calling ignoreVCSIgnored(true), for two reasons. That option reads the .gitignore files, not git's index: a file tracked despite a rule (git add -f) escapes the check.

Moreover, until 29 September 2026, Symfony Finder only found the repository root when .git was a directory. In a worktree, .git is a file: the root .gitignore was ignored, and the selection differed from the CI's. The fix shipped in Symfony 6.4.47, 7.4.20 and 8.1.8; the 3.95.27 image, built before, keeps the old behaviour.

4. The Symfony services: local first, CI on top

symfony.yml describes the tasks as they run on a developer machine, in the service's container, knowing nothing about the CI.

# .moon/tasks/symfony.yml
inheritedBy:
  tag: symfony
# Applies to every inherited task of the service, format and docker-build included.
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://^ stands for every project in dependsOn: a change to app-contracts makes the services' tasks affected. The audit goes through Composer's official image: with --locked, it only reads composer.json and composer.lock, without vendor/. --abandoned=report reports abandoned packages without failing the task.

ci.yml adds what a runner lacks, under the same task ids, with the same condition:

# .moon/tasks/ci.yml
inheritedBy:
  tag: symfony
tasks:
  ci-test-image:
    # The image name compose.yml expects, sources and vendor/ included.
    command: docker buildx build --target test --load --tag app/$project:test .
    options:
      cache: false
      internal: true
      runInCI: only
  install:
    # vendor/ is already in the test image.
    options:
      runInCI: skip
  lint:
    deps: [ci-test-image]
  test:
    deps: [ci-test-image]

runInCI: only runs a task in CI only: on a developer machine, ci-test-image does not run. skip does the opposite, while keeping the relationship valid: moon refuses a task run in CI that depends on a task with runInCI: false. In CI, the workflow sets COMPOSE_FILE=compose.yml: without the development override, php runs on the test image.

The options are written task by task: that is the trap of these files. A taskOptions, like implicitInputs or implicitDeps, applies to every inherited task of the project, not only to the file's own. A taskOptions: { runInCI: only } at the top of ci.yml would make every task of the service CI-only.

5. An explicit merge order

Without order, moon merges the files by increasing weight. The weight adds 50 for a toolchain or a language, 100 for a stack, 150 for a layer and 500 for tags. On a tie, moon sorts by file name.

The order field is not in the documentation, but it is in moon 2's configuration schema.

# .moon/tasks/docker-php.yml
inheritedBy:
  tags:
    and: [docker, symfony]
  # After docker.yml (500): these arguments follow its command.
  order: 600
tasks:
  docker-build:
    args: [--target, frankenphp_prod]

docker.yml defines the command, docker buildx build --tag app/$project:ci ., with the docker tag as its condition. Both files weigh 500, and docker-php.yml sorts before docker.yml: the hyphen comes before the dot. Without order, the command would become docker --target frankenphp_prod buildx build ..., which Docker rejects.

docker-node.yml adds deps: [build] to the same docker-build, and its computed weight is already 600 (tag and stack). We still write it: the order must not depend on a condition added later.

6. An audit that is never cached

# .moon/tasks/node.yml (excerpt)
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

An advisory is published without any input changing: with the cache, moon would replay an old success. cache: false does not decide when the audit runs: runInCI: always would run it on every pull request, even with no affected project. We keep the affected projects, plus a scheduled run on the main branch.

7. One workflow, one 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

With no path filter, the workflow runs on every pull request: a required check that never triggers stays pending and blocks the merge. With no affected project, moon ci runs nothing and succeeds.

Each matrix job runs moon ci, which our article on pipelines advises against: on main, each job would compute its own base. This workflow only runs on pull_request, where all jobs read the same base, the target branch.

quality-gate is the only required check: the name of a matrix job changes with its values. For GitHub, a job skipped by a condition counts as a success. Our article on pipelines accepts it, because its image job is skipped when there is nothing to build.

Here, checks has no condition: a skipped can only come from a disabled job, and the gate fails.

Checklist

  • The same task names for every stack.
  • language, stack, layer and tags declared in each moon.yml.
  • One .moon/tasks/ file per stack, and an explicit order when the merge depends on it.
  • Local tasks, completed by a CI file with runInCI: only.
  • No file-level option that should not apply to every task.
  • project://^ as an input of the tasks that use an internal package.
  • An audit without cache.
  • A single PHP-CS-Fixer configuration, run from its image.
  • A single required check, failing as soon as a job is not success.

Sources

Versions checked on 15 November 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 and docker/setup-buildx-action 4.4.1.