The monorepo-versus-polyrepo debate gets argued as if one is objectively correct, usually by citing a specific painful multi-repo migration or a well-known single-repo giant. Both structures work at scale — some of the largest engineering organizations run one enormous monorepo, and plenty of others run thousands of independent repos — which is a strong signal the choice is about what trade-offs your organization is better equipped to absorb, not which one is right.

What a Monorepo Actually Buys You

Atomic cross-project changes are the headline benefit: a shared library's API changes, and the same commit updates every caller, verified by one CI run, with no window where callers are on an incompatible version of a dependency they haven't updated yet.

text
One commit:
  libs/auth/token.ts          (breaking change)
  services/api/handler.ts     (updated call site)
  services/worker/consume.ts  (updated call site)
  -> single CI run verifies all three together, or the commit doesn't merge

It also makes code genuinely discoverable — one clone, one search, no guessing which of forty repos has the utility function you need — and simplifies dependency management, since there's exactly one version of any shared library in use at any moment, not a matrix of versions across repos slowly drifting apart.

What It Costs

The atomic-change benefit is also where the pain concentrates: tooling has to scale to the whole repo's size, which means investing in incremental build systems (Bazel, Nx, Turborepo) essentially becomes mandatory once the repo passes a certain size — a plain full install-and-test run across a multi-million-line monorepo is not a viable CI pipeline. Access control gets harder too: a monorepo either grants broad read access to the whole codebase or needs a path-based permission system layered on top, neither of which is free.

What a Polyrepo Actually Buys You

Independent deploy cadence is the real advantage, not "organization" in the abstract — a team can version, release, and roll back its service without any coordination with other teams' release schedules, and CI for one repo doesn't slow down because an unrelated repo's test suite is broken. Ownership boundaries are also enforced structurally rather than by convention: repo-level access control is the default, not an add-on.

What It Costs

Cross-cutting changes become their own project. Updating a shared library used by twelve services means twelve separate PRs, twelve separate review cycles, and, critically, a real window where some services are on the old version and some are on the new — which is either fine for a backward-compatible change or a genuine multi-week coordination effort for a breaking one. Dependency drift is the standing tax: without deliberate process, services quietly diverge on library versions until an upgrade becomes its own multi-sprint project.

The Actual Decision

Signal Leans toward
Shared libraries change often, many consumers Monorepo
Teams need independent release cadence, minimal coordination Polyrepo
Org has, or will invest in, build tooling maturity Monorepo
Strict per-team access boundaries are a hard requirement Polyrepo
Small number of teams, high cross-team collaboration Monorepo
Many autonomous teams, low cross-team coupling Polyrepo

Neither choice is permanent or irreversible in principle, but migrating between them is expensive enough in practice that it's worth being honest about which trade-offs your org already struggles with — a monorepo doesn't fix a coordination problem, and a polyrepo doesn't fix a discoverability problem; each just relocates where the cost shows up.

A worked example

Monorepo: one CI graph, atomic PRs across lib + app, Bazel/Nx affected tests. Polyrepo: team autonomy, separate versioning, consume via packages. You pick monorepo when APIs churn together; polyrepo when a library is truly published with a stability contract.

A hybrid: monorepo for the product, polyrepo for the public SDK.

Failure modes

Monorepo without affected-test selection (hour CI). Polyrepo with copy-paste and 12 versions of a util. Access control fights in a mono. Tag soup in poly. Tooling religion.

Pretending git submodules are a third way without pain.

When this is the wrong tool

A single service: one repo. Do not monorepo unrelated companies. Do not polyrepo a 4-package app to look distributed. If your VCS host cannot ACL a mono, that is a constraint. Multi-language without a build system will suffer in a mono. Avoid "one repo per microservice" plus a unpublished shared lib that is copied.

A worked failure mode

A monorepo is created without CI that can test affected packages; every commit builds the world for 40 minutes. A polyrepo split loses atomic API changes; teams pin stale clients. The failure is repo topology without tooling. Monorepo needs selective CI; polyrepo needs versioning discipline.

Neither topology fixes a lack of ownership. Do not monorepo to force friendship. Choose based on change coupling and CI investment.

A second, quieter failure is operational: the idea is copied from a talk into a path that has no rollback, no owner, and no metric that would show the invariant breaking. For "Monorepo vs. Polyrepo: The Trade-offs That Actually Matter", that usually means a Friday deploy with production as the first realistic test. Write down the user-visible symptom, the invariant, and the revert before you scale the pattern. If revert is a data rewrite, you do not have a revert—you have a project. Practice the failure in staging with production-sized data at least once, or you will practice it on customers.