Synthetic monorepo matrix: which jobs should run for five changes and a default-branch push

An invented repository

Synthetic example: every name, number and result below is invented for illustration. It is not a client's work, a measurement or a delivery by us.

Assume six packages. ui and api-client are libraries with no dependencies on each other. web depends on ui and api-client. admin depends on ui. billing-worker depends on api-client. docs-site stands alone. A root README and the lockfile sit outside any package. The dependencies are declared in each package's manifest, which is what lets a tool derive the graph.

If the matrix is wider than the box, scroll horizontally to read every column. Keyboard: focus the matrix and use Left/Right.

ui            <- web, admin
api-client    <- web, billing-worker
docs-site     (no dependants)
web, admin, billing-worker: leaf packages (nothing depends on them)

Five test changes and the expected jobs

Before anything runs, the table below is agreed. The expected set is the changed package plus every package that depends on it, and the summary check always runs. The lockfile row assumes the repository has been set up so that a lockfile change affects only the packages whose dependencies changed; with default behaviour in some tools, any lockfile change would run every package, which is also a legitimate agreed choice.

• A shared package change runs its dependants.
• A leaf change runs only itself.
• A change outside any package runs none of the package jobs, but the summary check still reports.

If the matrix is wider than the box, scroll horizontally to read every column. Keyboard: focus the matrix and use Left/Right.

change                                   | expected package jobs
1 edit the root README                    | none (summary check only)
2 edit admin                             | admin
3 edit ui                                | ui, web, admin
4 edit api-client                        | api-client, web, billing-worker
5 lockfile change touching only billing-worker's dependency | billing-worker
push to the default branch               | all six packages

Why the summary check matters

On change 1 no package job runs. If the required check were a package job skipped by a path filter, the pull request would wait forever. A single summary job that always runs, waits for the jobs that were supposed to run and passes when they passed or were correctly skipped, lets that pull request merge. The same job fails if a job that should have run, for example web on change 3, did not run. In this invented repository, the summary check is the only required check.

What this example proves, and the next step

Synthetic example: every name, number and result below is invented for illustration. It is not a client's work, a measurement or a delivery by us. No pipeline ran and no time was measured. The expected sets follow from the invented graph.

For a real repository, the fixed job starts at £795, untested, after a quote based on your workspace layout and how CI is triggered, and is paid after five agreed test changes run the expected jobs, a documentation-only change can merge and the default branch runs everything, and you sign off. No time saving is promised.