Poucas decisões de infraestrutura geram opiniões tão fortes quanto a estrutura de repositórios. Pessoas que trabalham em monorepos grandes defendem com entusiasmo. Pessoas que trabalham em polyrepos também. Os dois lados têm experiências reais e legítimas.

O problema é que essa decisão raramente é feita com critério — ela costuma ser herdada de como o primeiro repositório foi criado, ou copiada de uma empresa famosa sem considerar que o contexto é completamente diferente. Este post tenta apresentar os critérios reais para fazer essa escolha conscientemente.

O que é cada um

Monorepo é um único repositório Git que contém múltiplos projetos, serviços ou bibliotecas. Google, Meta, Microsoft e Shopify são exemplos de empresas que usam monorepos para a maior parte do código.

Polyrepo é o oposto: cada serviço ou biblioteca tem seu próprio repositório. É o modelo padrão do GitHub, o que a maioria das pessoas conhece.

Vale notar que nenhum dos dois é uma estratégia nova. O debate existe há décadas. O que mudou é o tamanho das bases de código e as ferramentas disponíveis para gerenciar cada abordagem.

As vantagens reais do monorepo

Mudanças atômicas entre projetos. Se você tem um componente compartilhado e precisa mudar sua interface, em um monorepo você faz a mudança na biblioteca e atualiza todos os consumidores em um único commit. Não há versão intermediária quebrada, não há janela de incompatibilidade.

Visibilidade total do código. Qualquer desenvolvedor pode ver, buscar e entender qualquer parte do sistema. Não há silos de conhecimento por repositório. Isso facilita refatorações amplas e torna mais fácil entender como as partes se encaixam.

Compartilhamento de ferramentas e configuração. Linting, formatação, configuração de testes, scripts de build — tudo fica definido uma vez e se aplica a todos os projetos. Manter consistência é muito mais fácil.

Code review com contexto completo. Um pull request pode incluir mudanças no backend, no frontend e na biblioteca compartilhada ao mesmo tempo. O revisor vê o impacto completo da mudança, não fragmentos em PRs separados.

As vantagens reais do polyrepo

Autonomia de times. Cada time é dono completo de seu repositório. Pode escolher suas ferramentas, seu ciclo de deploy, suas convenções. Não precisa negociar com outros times sobre configuração compartilhada.

Permissões granulares. Acesso a repositório é uma unidade natural de controle. Em um polyrepo, dar acesso a um contratante externo para trabalhar em um serviço específico não implica dar acesso ao resto do código.

Pipelines de CI mais simples. Cada repositório tem seu próprio pipeline. Uma mudança no serviço A não dispara testes do serviço B. Em monorepos, decidir o que testar quando algo muda requer ferramentas de análise de dependências.

Menor custo inicial. Polyrepo é a abordagem padrão. Não requer ferramentas especiais, não exige que o time aprenda conceitos novos. Você cria um repositório e começa a trabalhar.

Os problemas que cada um cria

Monorepos ficam lentos conforme crescem. git clone, git status, CI — tudo fica mais lento quando há dezenas de milhares de arquivos. Google e Meta resolveram isso com ferramentas internas que a maioria das empresas não tem acesso ou capacidade de replicar. Ferramentas open source como Nx e Turborepo ajudam, mas têm curva de aprendizado e limitações.

Polyrepos criam fricção de coordenação. Quando você precisa de uma mudança em uma biblioteca compartilhada que está em outro repositório, você precisa: fazer PR no repositório da biblioteca, esperar o merge, publicar uma nova versão, atualizar a versão no repositório consumidor, fazer outro PR. Em um dia normal, isso pode tomar horas. Vezes vinte serviços consumidores, é uma operação que pode durar semanas.

Comparação objetiva

Critério	Monorepo	Polyrepo
Mudanças cross-service	Simples — um commit	Complexo — múltiplos PRs e versões
Autonomia de times	Menor — configuração compartilhada	Maior — cada time decide
Controle de acesso	Mais difícil	Natural por repositório
Velocidade do Git	Degrada com o tamanho	Estável por repositório
CI/CD	Requer análise de impacto	Isolado por serviço
Visibilidade do código	Total	Fragmentada
Custo de adoção	Alto — exige ferramentas	Baixo — padrão do mercado

Quando cada um faz sentido

Monorepo faz sentido quando os serviços são altamente interdependentes e mudanças frequentemente precisam cruzar fronteiras. Quando o time é pequeno o suficiente para trabalhar no mesmo espaço sem conflito excessivo. Quando você tem ou está disposto a investir em ferramentas de build incremental.

Polyrepo faz sentido quando os serviços são verdadeiramente independentes e têm ciclos de deploy diferentes. Quando times têm autonomia tecnológica — diferentes linguagens, diferentes stacks. Quando há restrições de segurança que exigem isolamento de acesso por serviço.

Existe também uma terceira opção que muitas equipes adotam na prática: um monorepo por domínio. O time de pagamentos tem um repositório com todos os serviços de pagamento. O time de usuários tem o seu. Isso captura boa parte dos benefícios do monorepo — mudanças atômicas dentro do domínio, visibilidade interna — sem o custo de coordenar um único repositório gigante.

Conclusão

Não existe resposta certa universal. A escolha depende do tamanho do time, do grau de acoplamento entre os serviços, da capacidade de investir em ferramentas e das restrições de acesso e segurança.

O que existe são escolhas feitas sem critério — e essas costumam gerar arrependimento. Migrar de polyrepo para monorepo depois que você tem 50 repositórios é doloroso. Migrar de monorepo para polyrepo quando o repositório tem 5 anos de história é ainda pior.

Vale a pena sentar, entender o que seu time realmente precisa e tomar essa decisão com calma — de preferência antes de precisar desfazê-la.