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.jsonscripts. - 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.
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,layerand tags declared in eachmoon.yml. -
One
.moon/tasks/file per stack, and an explicitorderwhen 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
auditwithout 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.
-
moon,
task inheritance:
inheritedByconditions, clauses and merge strategies. -
moon,
.moon/tasks:
implicitInputs,implicitDepsandtaskOptions. -
moon,
v2 schema of the task files
(
inheritedBy.order); default weights and sort by name in inherited_tasks_config.rs and inherited_tasks_manager.rs. -
moon,
project configuration:
language,args,cache,runInCI,project://inputs. - moon, commands ci, project and task; targets, tokens and query language.
-
PHP-CS-Fixer,
installation
(Docker image),
usage
(
--path-mode) and Finder. -
Symfony,
Finder component
(
ignoreVCSIgnored) and fix for a .git file. -
Git,
git-worktree
(a worktree's
.gitfile) and gitignore (files already tracked). - vscode-php-cs-fixer: formatting a temporary copy.
-
Composer,
audit command
(
--locked,--abandoned) and official image; Yarn, yarn npm audit. - Docker Compose, merging files and COMPOSE_FILE.
- GitHub, needs context and Troubleshooting required status checks.
- Lychen, pull requests 245, 246, 247 and 250: an open-source implementation of this task interface and its quality gate, in a moon monorepo.