Polyrepo

Pronunciation: POL-ee-ree-poh

Updated October 6, 20262 min read

In short

A polyrepo is a setup where each project, service or library lives in its own version control repository, with its own history, pipeline and release cycle.

What is a polyrepo?

In a polyrepo setup, also called multi-repo, an organization gives every project its own repository: the web app, the mobile app, each backend service and each shared library are kept apart. It is how most teams and nearly all open-source projects work by default, since one repository per project is what hosting services such as GitHub and GitLab are built around. The word itself became common mainly as the counterpart of monorepo, where everything lives in one repository.

Each repository has its own history, access rules, CI pipeline and release schedule, so teams can work and deploy independently. Shared code is published as versioned packages, for example to npm or Maven, and other repositories depend on a specific version; some teams use Git submodules instead. Tools such as Dependabot and Renovate open pull requests automatically when a dependency has a new version.

A polyrepo is like a neighborhood of separate houses instead of one apartment building: each family has its own key and rules, but borrowing something means walking to the neighbor's door. The costs show up in changes that span repositories: updating a shared library means publishing a new version and then upgrading every consumer in separate pull requests, versions drift apart over time, and build tooling and configuration get duplicated.

Polyrepo vs monorepo is about where code is stored, not how it runs. Microservices don't require a polyrepo, and a monolith can still pull in libraries from other repositories. Monorepos make cross-project changes atomic and keep everything on the same version, while polyrepos give each team autonomy and keep repositories small and fast, and many organizations mix the two, with a few monorepos per product area.

Key takeaways

A polyrepo gives each project or service its own repository.
Teams get independent histories, permissions, pipelines and releases.
Shared code travels as versioned packages or Git submodules.
Changes across repositories need several pull requests and version upgrades.
Monorepo vs polyrepo is about code storage, not about microservices vs monoliths.

Example

Releasing a shared library in a polyrepo setupbash

# The shared library and the app live in separate repositories
git clone git@github.com:acme/ui-kit.git
git clone git@github.com:acme/web-app.git

# 1. Change the library, then release a new version
cd ui-kit
npm version minor      # 2.3.0 -> 2.4.0, with a commit and a Git tag
npm publish

# 2. The app upgrades when its team is ready, in its own pull request
cd ../web-app
npm install @acme/ui-kit@2.4.0
git commit -am "chore: upgrade ui-kit to 2.4.0"

Readers ask

What is the difference between a polyrepo and a monorepo?

A polyrepo gives each project its own repository, while a monorepo keeps many projects in one. Polyrepos favor team independence and small repositories; monorepos favor shared tooling and atomic changes across projects.

Are microservices always in a polyrepo?

No. How code is stored is independent of how it is deployed. Many companies keep dozens of microservices in a single monorepo, and others split one application's libraries across several repositories.

How do you share code between repositories in a polyrepo?

Usually by publishing it as a versioned package to a registry such as npm, Maven or PyPI, often a private one. Git submodules are another option, but they are harder to work with day to day.