Stop 04 · Git & Version ControlTopics · 6/8

Monorepos vs Polyrepos (Overview)

In short

Should your ten services live in one big repo or ten small ones? Both work at big companies. The choice changes how you build CI, share code and decide who owns what.

A monorepo keeps all (or many) projects in a single repository; polyrepos split them into separate repositories per project — each approach has real trade-offs for tooling, ownership, and CI/CD complexity.

The mascot stands between one big family house and a row of small separate houses.

Think of it like this

Joint family vs separate flats

In a joint family, everyone lives under one roof. Sharing is easy, but one leaking tap affects the whole house and decisions take a family meeting. Nuclear families in separate flats run their own homes, but borrowing sugar means a trip upstairs. Monorepo and polyrepo, exactly.

Watch it happen

One repo or many?

Monorepo

One change can update many services
Shared code and tooling in one place
CI must build only what changed

Polyrepo

Each service has its own repo
Clear ownership and simple pipelines
Shared changes need many PRs

Small teams often start with a monorepo for simplicity. Large orgs with independent teams often prefer polyrepos, or invest in monorepo build tools.

The big ideas

What you need to know

CI is the big difference

A monorepo pipeline must detect which folders changed, or every commit rebuilds everything.

Ownership files help

A CODEOWNERS file maps folders to teams, so the right people review changes even in one big repo.

Sharing code

Monorepos import shared code directly. Polyrepos publish shared libraries as versioned packages.

No universal winner

Pick based on team size, how often services change together, and the tooling you can maintain.

See it in code

Walk through the code

yaml

1# GitHub Actions in a monorepo: only build the API when it changes2on:3  push:4    branches: [main]5    paths:6      - "services/api/**"7      - "libs/shared/**"8 9jobs:10  build-api:11    runs-on: ubuntu-latest12    steps:13      - uses: actions/checkout@v414      - run: make -C services/api build

1/3Run on pushes to main...

Path filters are the simplest trick for monorepo CI. Bigger monorepos use build tools that work out the dependency graph for you.

Save yourself the pain

Common mistakes

Oops

Moving to a monorepo but keeping one pipeline that builds everything on every commit.

Do this instead

Add path filters or a build tool that only builds and tests what actually changed.

Oops

Splitting into 30 tiny repos on day one for a three-person team.

Do this instead

Start simple. Split repos when ownership or release cycles truly differ.

Your mission

Design both layouts

~20 min

Quick check

In a monorepo, a change to libs/shared should trigger which builds?

Go deeper

1List 2 advantages and 2 disadvantages of a monorepo versus separate repositories.
2Learn why large tech companies (Google, Meta) famously use massive monorepos with custom tooling.
3Understand this is a real architectural decision, not just a matter of preference.