Monorepo vs multirepo: critérios objetivos para escolher

1. Definições e contexto da decisão arquitetural

Monorepo (monolithic repository) é um único repositório que abriga múltiplos projetos, serviços, bibliotecas ou aplicações. Tudo vive no mesmo espaço de versionamento, com um histórico compartilhado. Multirepo (multi-repository) é a abordagem oposta: cada projeto, serviço ou componente tem seu próprio repositório independente, com ciclo de vida, versionamento e permissões próprios.

A escolha entre essas arquiteturas não é estética nem dogmática. Ela impacta diretamente a produtividade do time, a velocidade de entrega, a complexidade das integrações e a capacidade de escalar a organização. Decisões erradas geram retrabalho, conflitos de merge constantes e pipelines lentos.

2. Critérios baseados em tamanho e complexidade da equipe

O número de desenvolvedores e a frequência de commits concorrentes são os primeiros termômetros. Em equipes com até 10 desenvolvedores trabalhando em projetos fortemente acoplados, o monorepo reduz a fricção: todos veem as mudanças em tempo real, e os conflitos de merge são gerenciáveis.

Acima de 50 desenvolvedores, o cenário muda. Em multirepo, cada time opera com autonomia total, sem se preocupar com o que os outros estão fazendo. Já no monorepo, a coordenação se torna um gargalo sem ferramentas adequadas:

# Exemplo de conflito frequente em monorepo sem coordenação
# Dois desenvolvedores modificam o mesmo arquivo de configuração
<<<<<<< HEAD
API_TIMEOUT = 30000
=======
API_TIMEOUT = 60000
>>>>>>> feature/timeout-increase

Para equipes acima de 100 desenvolvedores, monorepo exige investimento pesado em ferramentas de build incremental e detecção de impacto. Sem isso, o tempo médio de merge pode ultrapassar horas.

3. Critérios de dependências e versionamento

No monorepo, dependências compartilhadas vivem em um único lugar. A atualização de uma biblioteca interna é atômica: todos os consumidores recebem a mudança no mesmo commit. Isso elimina o famoso "dependency hell" de versões incompatíveis:

# Monorepo: dependência compartilhada no workspace root
// package.json (root)
{
  "workspaces": ["packages/*"],
  "dependencies": {
    "shared-utils": "1.0.0"
  }
}

No multirepo, cada repositório gerencia suas próprias dependências. Uma atualização de biblioteca exige propagação manual em N repositórios, com riscos de esquecimento e versionamento divergente:

# Multirepo: cada repositório tem seu próprio package.json
// service-a/package.json
{
  "dependencies": {
    "shared-utils": "^1.0.0"
  }
}

// service-b/package.json
{
  "dependencies": {
    "shared-utils": "^1.2.0"  # versão diferente!
  }
}

A escolha depende do acoplamento real entre os projetos. Se há dependências compartilhadas com atualizações frequentes, monorepo ganha. Se os projetos são independentes, multirepo evita o overhead de coordenação.

4. Critérios de CI/CD e automação

O impacto no pipeline de CI/CD é um dos critérios mais práticos. Em monorepo, builds incrementais são essenciais. Ferramentas como Nx, Turborepo e Bazel detectam quais projetos foram afetados por uma mudança e só reconstroem o necessário:

# Comando Nx: build apenas dos projetos afetados
nx affected:build --base=main --head=feature-branch

# Saída esperada:
# ✔  nx run api:build  (1s)
# ✔  nx run web:build  (3s)
# ✔  nx run shared:build  (0.5s)
# Total: 4.5s (em vez de 30s de build completo)

Em multirepo, cada repositório tem seu próprio pipeline independente. O deploy pode ser feito por serviço, sem risco de quebrar outros componentes. A desvantagem é a duplicação de configuração e a falta de visibilidade do impacto entre repositórios.

5. Critérios de governança e segurança

O controle de acesso é outro divisor de águas. Em multirepo, permissões são granulares por repositório: o time de front-end não tem acesso ao repositório de back-end. Em monorepo, o acesso é por diretório, exigindo ferramentas como CODEOWNERS para aplicar revisões obrigatórias:

# .github/CODEOWNERS - monorepo
# Time de front-end é responsável pela pasta web/
/web/ @team-frontend

# Time de back-end é responsável pela pasta api/
/api/ @team-backend

# Mudanças em shared/ exigem aprovação de ambos
/shared/ @team-frontend @team-backend

Para rastreabilidade de vulnerabilidades, o monorepo oferece visibilidade centralizada: um único scan de dependências cobre todos os projetos. No multirepo, cada repositório precisa ser escaneado separadamente, o que aumenta o risco de falhas de compliance.

6. Critérios de escalabilidade e ferramentas

Git não foi projetado para repositórios com milhões de arquivos. Monorepos gigantes (como o do Google) exigem estratégias especiais:

# Clonagem parcial para evitar baixar todo o histórico
git clone --depth 1 --filter=blob:none <url-do-repositorio>

# Sparse checkout: baixar apenas diretórios necessários
git sparse-checkout init --cone
git sparse-checkout set packages/api packages/shared

Ferramentas como Git LFS e GVFS (Git Virtual File System) ajudam, mas aumentam a complexidade operacional. Para a maioria das empresas, repositórios com até 10GB e 50 mil arquivos são gerenciáveis sem ferramentas especiais.

7. Matriz de decisão e exemplos práticos

Critério Monorepo Multirepo
Equipe pequena (< 10 devs) ✅ Excelente ❌ Overhead desnecessário
Equipe grande (> 50 devs) ⚠️ Requer ferramentas ✅ Autonomia total
Dependências compartilhadas ✅ Atualizações atômicas ❌ Propagação manual
Microsserviços independentes ❌ Acoplamento indesejado ✅ Isolamento natural
CI/CD rápido ⚠️ Build incremental necessário ✅ Pipelines independentes
Controle de acesso granular ⚠️ CODEOWNERS + ferramentas ✅ Por repositório

Casos reais:
- Google, Meta e Microsoft adotam monorepo — com investimento massivo em ferramentas internas (Bazel, Buck, custom Git)
- Empresas de microsserviços como Netflix e Amazon preferem multirepo para autonomia de times
- Micro-frontends com Module Federation frequentemente usam multirepo para deploy independente

Checklist final para sua decisão:

  1. Seu time tem menos de 20 desenvolvedores? → Monorepo
  2. Seus projetos compartilham código base com frequência? → Monorepo
  3. Você precisa de deploys independentes por serviço? → Multirepo
  4. Seu time tem maturidade para ferramentas de build incremental? → Monorepo
  5. O controle de acesso por projeto é requisito de segurança? → Multirepo

Não existe resposta certa universal. A escolha depende do equilíbrio entre autonomia dos times, acoplamento de código e capacidade operacional da organização.

Referências