What Is a Monorepo?

If monorepos are different beasts at different scales, do they have anything in common? Or does having a single term for such varied technologies do more harm than good?

To be sure, some engineers¹ complain about the squishiness of the word. One repo for what? At what scope? Isn’t every repo a monorepo? What value does this word even provide when we could just say “repo?”

But the descriptivist angel on my shoulder reminds me that terminology persists in culture for a reason.² So it’s worth unpacking why. The power of this abstraction is that it conveys something about the intent of organizing a codebase into a single repository. Let’s attempt a working definition:

A monorepo is a codebase with guaranteed atomicity for code merges and software release candidates.

In other words, if we take as fixed that we have some codebase we’re working with, a monorepo is a specific strategy for how to organize that codebase for the purpose of particular workflows. In particular, monorepos optimize for atomicity of code merges:

Where a polyrepo assembles release candidates by selecting specific revisions of components in a dependency graph, a monorepo subsumes the source of the dependency graph and guarantees that all changes anywhere across the graph are atomically merged into a single-threaded history.

Benefits of Monorepos

A comprehensive, single-threaded codebase has strong implications for productivity:

• Builders merge their work into a single place, simplifying the day-to-day process of upstreaming feature work.
• Cross-cutting, even incompatible changes to shared abstractions and their use sites (up to a certain scale…) can be made without complex, multi-stage merge-and-release orchestrations.
• Tech leads enjoy easier oversight of the codebase (e.g., coding standards, external dependency curation).
• Searching, navigating, and understanding code relationships across the codebase is internally consistent since builders operate on coherent snapshots.
• Internal dependencies cannot, by definition, fall out of date.
• Release candidates can be fully assembled as part of the build without requiring additional machinery.

Challenges of Monorepos

Monorepos are not a magic wand. As with polyrepos, they come with their own challenges:

• Build scalability: Advanced tooling is required to ensure that typical workflows that change only small portions of the codebase require a minimum of rebuilding.
• Test hygiene: Flaky tests are far more destructive to productivity in a large repo: one team’s unpredictable test can ruin test repeatability for everyone across the entire codebase.
• Storage and retrieval scalability: Local disk space usage, repo sync speed, rate limiting, efficient and safe merging can become bottlenecks as repo size increases.
• Governance: Naive ownership systems that configure roles (e.g. reviewer privileges) and responsibilities (e.g. on-call) on a per-repo boundary do not scale; monorepos require sub-repo governance solutions.
• Privacy: Even in inner source settings, some organizations require restricting visibility to certain sensitive parts of a codebase. This may be supported by some off-the-shelf SCM systems but certainly not all.
• Validation: Even though merges are atomic, a monorepo may or may not guarantee that validation of merges is performed atomically. Without solutions like merge queues or merge trains, which provide stronger guarantees about the atomicity of built+test+merge, race conditions can cause concurrently validated merges to break the tree.
• Independent release: Monorepos optimize for dealing with all components at the latest version. Supporting complex release orchestration semantics requires additional machinery, and some use cases like deploying emergency patches to older versions can be an awkward fit.

Takeaway: Keep Learning!

This is not a complete list, but it’s a place to start. My intent isn’t to overwhelm but, short of a grand unified theory, I feel at least I can ground a controversial topic with some structure.

Maybe some day we will get to a point where repo strategy is a straightforward and automatable decision, but today it still requires judgment and planning. And the costs and benefits are undoubtedly going to keep changing as the current upheaval of software engineering continues. So for now, it’s still a good idea for all engineers to learn these basics of repo design and their practical implications.