How to Write a Monorepo Adoption Review (with a Template)

Write the reason as a measurement

“Easier to manage” is not a reason a reviewer can test. Record how long a typical cross-repository change takes and how often files that change together live in different repositories. This site has collected 3 monorepo-topic posts so far, 2 of which describe a migration.

What the migration cases show

CyberAgent checked how a Go 1.27 update would affect its advertising monorepo before rolling it out. A single language-version change reaches every service in a monorepo at once, so the review should say which services are in scope and which checks cover them.

Cutting CI time is the main cost to plan for

The largest cost of a monorepo is running everything on every change. Stripe’s selective test execution for a 50-million-line Ruby monorepo is the pattern to evaluate: choose tests from the change set. The review should list what a wrong selection would miss, not only the time it saves.

Set the reversal condition in advance

Once combined, a monorepo is expensive to split again. Put a numeric build-time target on the first page of the review, and write the condition that triggers a return to separate repositories, such as missing the target for several weeks in a row.

Template (copy)

## 1. What we would combine, and why

- Code that changes together, code that must ship on its own

## 2. Current bottlenecks

- Build time, test time, permission friction (write them as measurements)

## 3. Options

| Option | Benefit | Cost | How to reverse |
|---|---|---|---|
| Monorepo | | | |
| Keep separate repositories | | | |

## 4. Migration plan

- Phases, build cache, ownership rules

## 5. Success metrics and reversal triggers

- Build time target, and the condition that sends us back