Monorepo ou polyrepo: escolhendo uma abordagem

There are two ways to organize code across many projects:

• Monorepo — all projects in one repository
• Polyrepo — each project in its own repository

Neither is universally right; the choice depends on team size, coupling, and tooling.

In polyrepo each service or library has its own repo, history, and release cycle. Teams own their repos independently.

A monorepo holds everything under one root, with directories per project sharing one history and one set of tooling.

Strengths of a monorepo:

• Atomic changes across projects in one commit
• Single source of truth for shared code
• Easier large-scale refactoring
• Unified tooling and CI configuration

Costs to plan for:

• Repository can grow very large
• CI must be smart to build only affected projects
• Access control is coarser by default
• Tooling investment is required up front

Strengths of polyrepo:

• Clear ownership boundaries
• Smaller, faster clones and CI per repo
• Independent release cadence
• Fine-grained access control

Costs of polyrepo:

• Cross-repo changes need coordinated PRs
• Shared code drifts across versions
• Dependency upgrades fragment
• Discovery and consistency are harder

In polyrepos, two services depending on different versions of a shared lib causes painful conflicts. Monorepos avoid this with a single, always-current version of shared code.

A rule of thumb:

• Tightly coupled projects that change together favor a monorepo
• Loosely coupled, independently shipped services tolerate polyrepo well

Many organizations mix both: a monorepo per domain or team, with separate repos for clearly independent products. The boundary should follow how code actually changes together.

Moving polyrepos into a monorepo is doable while preserving history (e.g. with git subtree or import tools), but commit to the tooling investment first — it is the deciding factor.

You can now reason about repository strategy:

• Monorepo: atomic changes, shared code, unified tooling — at the cost of scale and CI complexity
• Polyrepo: clear ownership and independence — at the cost of cross-repo coordination and version drift
• Coupling and team structure drive the choice; hybrids are common

This sets up the monorepo structure and tooling lessons that follow.