The decision criteria — team size, coupling, CI performance, blast radius, security boundaries, and tool support

The decision between a monorepo, a multi-repo, and a hybrid is not a tooling preference. It is forced by six operational signals: team size, coupling, CI performance, blast radius, security boundaries, and tool support. The criteria are applied to the current state of the team and the codebase, and the answer is the shape that minimises the total cost: the cost of the model and the cost of the operational signals that the model does not solve.

The six criteria

The six criteria are not weighted equally; the team should walk through them in order, and the criterion that forces a shape wins:

1. Team size. A small team (3-10 engineers) is usually cheaper in a monorepo because the cross-repo glue is hand-maintained. A large team (50+ engineers) is usually cheaper in a multi-repo because the per-repository ownership is enforceable.
2. Coupling. If components must change in lockstep, the monorepo is cheaper. If components change independently, the multi-repo is cheaper.
3. CI performance. A monorepo requires a build graph; a multi-repo requires a cross-repo glue. The criterion is which investment the team can actually make.
4. Blast radius. High-blast-radius assets (network, IAM, secrets) should be in their own repository, regardless of the other criteria.
5. Security boundaries. Compliance regimes that require per-asset access control (PCI, HIPAA, FedRAMP) usually force a multi-repo shape.
6. Tool support. A monorepo needs a build graph (Bazel, Buck, or equivalent); a multi-repo needs a pinned-version registry. The criterion is which tool the team can run.

flowchart TD
    Q1{Team size?}
    Q1 -->|small| M[Monorepo candidate]
    Q1 -->|large| MP[Multi-repo candidate]
    M --> Q2{Components change in lockstep?}
    Q2 -->|yes| M
    Q2 -->|no| MP
    MP --> Q3{High-blast-radius asset?}
    Q3 -->|yes| SP[Scoped repo]
    Q3 -->|no| MP
    SP --> Q4{Tool support?}
    Q4 -->|yes| M
    Q4 -->|no| MP

Applying the criteria

The framework is applied by walking the criteria in order and recording the shape each criterion suggests. The shape that appears most often is the candidate; the criteria that force the opposite shape are the cost.

Consider a team of twenty engineers maintaining a codebase that includes Terraform, Ansible, Kubernetes manifests, and a small amount of application code:

• Team size. 20 engineers is in the middle. The monorepo is cheaper for the day-to-day work; the multi-repo is cheaper for the cross-team ownership.
• Coupling. The Terraform, Ansible, and Kubernetes manifests do change in lockstep (a service onboarding touches all three). The monorepo is the right shape for coupling.
• CI performance. The team has a CI matrix that runs per directory; the build graph is a list of paths, not a fully-keyed dependency graph. The monorepo is the cheaper shape for CI.
• Blast radius. The network Terraform is high-blast-radius. The network should be in its own repository, even though the rest of the codebase is in a monorepo.
• Security boundaries. The team is not under a compliance regime that forces per-asset access control. The monorepo is acceptable.
• Tool support. The team has no Bazel or Buck; the CI is GitHub Actions. The monorepo is the cheaper shape for tool support.

REPO_URL="https://github.com/example/infra-monorepo.git"

git clone --depth 1 "$REPO_URL"
cd infra-monorepo
git ls-files | wc -l

The verdict is a hybrid: a monorepo for the bulk of the codebase, with a scoped repository for the high-blast-radius network Terraform, and a pinned submodule reference from the monorepo to the scoped repository. The two trunks ship at their own speed; the consumer picks up the new version explicitly.

The cost of the wrong shape

The cost of the wrong shape is paid in the operational signals it does not solve:

• A monorepo that does not solve coupling. If the components do not change in lockstep, the monorepo pays the cost of a shared trunk without the benefit of atomic cross-component changes.
• A multi-repo that does not solve independence. If the components do change in lockstep, the multi-repo pays the cost of cross-repo coordination without the benefit of independent release cadence.
• A hybrid that does not solve the cross-repo glue. If the cross-repo glue is a hand-maintained file, the hybrid pays the cost of two models without the benefit of either.

Production discipline

1. Walk the six criteria in order. The criterion that forces a shape wins.
2. Apply the framework to the current state, not the aspirational state. A team that is small today will not be small forever; the framework is applied to today.
3. Treat the decision as a one-way door. Splitting a monorepo or merging a multi-repo is expensive; the decision should be made before the codebase is too large.
4. Verify the chosen shape with git ls-files | wc -l and the appropriate clone commands. A shape that is not verifiable is a shape that is not enforced.

Cross-course references

• Linux for Production Sysadmins - Part XXVI (RepoLayout) covers the filesystem analogue: a single root tree versus per-service trees, and the cost of the inode walk.
• Ansible for Production Sysadmins - Part XXXVII (RepoArch) covers the role-based layout of a single-tool Ansible repository, where the role is the unit of ownership.
• Terraform for Production Sysadmins - Part IX (State) covers why Terraform state is the strongest argument for scoping every high-blast-radius asset to its own repository.

Quiz