Should all your code live in one version-controlled repository, or should each service and library get its own? Engineers argue about this with surprising heat. I will take a side at the end, but the useful part is understanding what each option actually changes day to day, because the arguments for both are weaker in the abstract than they sound.

Definitions, without the ideology

A monorepo is one repository containing many projects: several services, shared libraries, perhaps web and mobile apps. It is not the same as a monolith. A monorepo can hold fifty independently deployed services. A polyrepo setup uses a separate repository per project or per team.

Google is the famous monorepo example, with a published paper describing its single, very large repository and the custom tooling built around it. Many other well-known companies also use monorepos, and many equally successful ones use thousands of small repositories. So success is not evidence for either side; what matters is whether the surrounding practices match.

What a monorepo gets you

Atomic cross-project changes. Suppose a shared validation library changes its function signature. In a monorepo, one pull request updates the library and every caller together, and the build proves nothing is broken before merge. In polyrepos, you publish a new library version, then open separate pull requests in every consuming repository, and for weeks the organisation runs a mix of versions.

Easier sharing and discovery. Anyone can search all the code, copy a pattern, or see who uses a function before changing it. This is a big help to a fresher trying to learn how the company writes things.

One set of standards. Linting rules, build setup, dependency versions and CI configuration can be maintained once. Dependency upgrades, such as fixing a security vulnerability in a library, happen in one place instead of forty.

What a monorepo costs

The costs are mostly tooling and discipline. Without a build system that understands dependencies, every change triggers a build and test of everything, and CI times balloon. Tools such as Bazel, Nx, Turborepo and Pants exist to build and test only what a change affects, and to cache results; adopting and learning them is real effort. Git itself slows down on very large repositories, though most companies are nowhere near the sizes where that bites.

Access control is blunter. If the whole repository is visible to everyone, you cannot easily hide one team’s code. Some platforms support path-based ownership files, such as the CODEOWNERS convention, which route reviews to the right owners, but restricting read access per folder is harder than simply having a private repo.

There is also a cultural risk: a monorepo makes it tempting to reach across boundaries, importing another team’s internal code because it is right there. Without enforced module boundaries, you grow a tangle, which is the distributed monolith problem wearing different clothes.

What polyrepos get you, and cost you

Polyrepos give clear ownership and clean boundaries. A repository has an owner, its own release cycle, its own permissions, and a small, fast build. Contractors or a partner team can be given access to exactly one repository. Boundaries are enforced because crossing them means publishing and consuming a versioned package.

The price shows up in coordination. Shared code must be versioned and published, and consumers upgrade on their own schedules, so old versions linger. A cross-cutting change needs many pull requests in many places, and it is easy to lose track of which services still run the old library. Tooling like Dependabot or Renovate automates the pull requests, but someone still has to review and merge them. Standards drift: each repository’s CI and linting slowly diverge. Finding code means knowing which repository to search, unless you invest in a code search tool.

Where the lines fall

SituationLeans towards
Small to mid team, tightly related services, frequent cross-cutting changesMonorepo
Many independent teams with separate release cycles and little shared codePolyrepo
Open-source libraries consumed by outsidersPolyrepo
Strict access separation between groups or vendorsPolyrepo
Web frontend, mobile app and backend sharing types and APIsMonorepo

My side

For a single product organisation with, say, 10 to 100 engineers, I would start with a monorepo. At that size the pain of coordinating versions across repositories is felt immediately, while the monorepo’s scaling problems are far away. Off-the-shelf tooling for JavaScript and Python projects is now reasonable, and the ability to change an interface and all its callers in one reviewed commit is worth a great deal. Set up path-based ownership and a rule that projects only depend on each other’s public interfaces, so the boundaries survive.

That is an opinion, and it flips in some cases: an IT services company, for example, builds separate products for separate clients, with different contractual confidentiality. One repository per client project is not just easier, it is nearly required. A company with a strong culture of independent teams and stable, versioned internal packages will also be fine with polyrepos.

Whichever you choose, the migration cost of changing later is high, so make the choice deliberately, write down why, and revisit it only when the pain is concrete: CI times that cannot be reduced, version drift that causes incidents, or access needs that cannot be met.

Leave a Reply

Trending