The trade-off — coupling versus independence, and what a single commit can affect

The choice between a monorepo and a multi-repo is a coordination choice: how many humans can change the same decision in the same commit, who can see which change in flight, and how much of the production system moves when a single merge lands.

The two properties at stake

The trade-off sits between two properties that cannot be maximised at the same time:

• Coupling. A monorepo makes “everything in one place” the default. A single commit can change a Terraform module, an Ansible role, and a Kubernetes manifest atomically; the dependent pieces never drift apart.
• Independence. A multi-repo gives each service its own trunk, its own review surface, its own blast radius, and its own release cadence. No component is held hostage by another component’s review window.

flowchart LR
    A["Repository boundary"] --> B["Coupling"]
    A --> C["Independence"]
    B --> D["Atomic cross-component change"]
    B --> E["Shared review surface"]
    C --> F["Independent blast radius"]
    C --> G["Independent release cadence"]

What a single commit can affect

In a monorepo, a single merge can change every directory the index contains. The blast radius of the commit is the union of every directory the change touches, and the visibility is the union of every reviewer’s notification list. In a multi-repo, the same logical change is several commits across several trunks; the blast radius of each individual commit is narrower, but the coordination of the change spreads across repositories. A change that lands in repository A but not in repository B can leave the system in a broken intermediate state.

Production discipline

1. Treat the repository boundary as the most consequential architecture decision in the codebase. It is harder to undo than a framework upgrade.
2. Name the coupling property you are protecting. If “atomic cross-component changes” is the answer, a monorepo is the right shape. If “independent blast radius” is the answer, a multi-repo is the right shape.
3. Verify visibility before committing. A git ls-files | wc -l on the trunk tells you the scope without the cost of a full clone.
4. Never let the boundary drift by accident. A folder added to a monorepo because “it is just one more service” is a folder that inherits the trunk’s blast radius.

Cross-course references

• Linux for Production Sysadmins - Part XXVI (RepoLayout) covers the filesystem analogue: one big /etc versus a per-service tree.
• Terraform for Production Sysadmins - Part IX (State) covers why Terraform state is the strongest argument for keeping Terraform in its own repository.

Quiz