O que é o Google Copybara

O Google Copybara e uma ferramenta open source criada pelo Google para automatizar a copia e transformação de código entre repositórios. O nome e uma referência ao capivara, mas o conceito e bem técnico: mover trechos de código de um lugar para outro de forma controlada e repetivel.

A ferramenta nasceu de uma necessidade interna do Google. A empresa usa um monorepo gigante para desenvolvimento interno, mas precisa publicar partes desse código em repositórios públicos no GitHub. Fazer isso manualmente e propenso a erros e consome muito tempo. O Copybara resolve esse problema com configurações declarativas e execução automatizada.

Ele foi publicado no GitHub e desde então e usado por times do Google como o Bazel, Abseil e vários outros projetos open source da empresa. Qualquer dev pode usar para seus próprios fluxos de sincronização entre repos.

Como funciona

O Copybara funciona lendo um arquivo de configuração chamado copy.bara.sky, escrito em Starlark, que é a mesma linguagem de configuração usada no Bazel. Nesse arquivo você define origens, destinos e transformações que devem acontecer durante a copia.

O fluxo básico e: o Copybara le os commits da origem, aplica as transformações configuradas como remover arquivos internos, substituir caminhos ou reescrever mensagens de commit e cria novos commits no repositório de destino. Ele suporta três modos principais de operação: squash, rebase e cherry-pick.

Por baixo dos panos ele usa JGit para operações Git e se integra com APIs do GitHub e Gerrit para criar pull requests automaticamente. A execução pode ser feita localmente ou em pipelines de CI/CD.

Principais recursos

O Copybara oferece um conjunto robusto de funcionalidades para quem trabalha com múltiplos repositórios:

  • Transformações de caminho: você pode renomear pastas e arquivos durante a copia, mapeando a estrutura interna para a estrutura pública sem esforço.
  • Exclusão de arquivos: arquivos confidenciais ou irrelevantes para o público podem ser excluídos automaticamente da copia.
  • Substituição de texto: referências internas como URLs, nomes de times ou comentários podem ser reescritos antes de chegar ao repo destino.
  • Criação automática de PRs: após a copia, o Copybara pode abrir um pull request no GitHub diretamente, sem intervenção manual.
  • Suporte a múltiplas origens: e possível combinar código de mais de um repositório em um único destino.
  • Feedback loop: contribuições externas podem ser trazidas de volta ao repositório interno de forma automatizada.

Como começar: instalação passo a passo

O Copybara e escrito em Java e requer Java 11 ou superior para rodar. A forma mais simples de instalar e via Bazel, que compila o binário diretamente do código-fonte.

Passo 1: instale o Bazel na sua máquina disponível em bazel.build. Passo 2: clone o repositório oficial com git clone https://GitHub.com/google/copybara. Passo 3: dentro da pasta, compile com bazel build. O binário gerado fica em bazel-bin/java/com/google/copybara/copybara.

Usuários de macOS podem instalar via Homebrew com brew install copybara. Após a instalação, crie o arquivo copy.bara.sky na raiz do projeto com a configuração da sua workflow e rode copybara copy.bara.sky default para executar.

Exemplo prático

Imagine que você tem um monorepo interno com a estrutura internal/meulib/ e quer publicar apenas essa pasta em um repositório público no GitHub. A configuração define a origem, o destino, os arquivos incluídos e o modo SQUASH para consolidar commits.

O arquivo copy.bara.sky define: origem (repo interno), destino (repo público), quais arquivos incluir com glob(), qual modo usar e as transformações a aplicar, como core.move() para remapear caminhos. Com isso, ao rodar o Copybara ele pega tudo que esta em internal/meulib/ e move para a raiz do repo destino.

Na prática, após configurar, o comando para executar e simples: copybara copy.bara.sky default. Para testar sem gravar nada, use copybara copy.bara.sky default --dry-run e inspecione o resultado antes de confirmar.

Comparação com alternativas

Existem outras formas de sincronizar código entre repositórios. O git subtree e o git submodule são nativos do Git, mas exigem mais configuração manual e não oferecem transformações. O semantic-release foca em versionamento, não em migração de código.

Para scripts customizados em shell ou Python, o problema e a manutenção: cada time acaba reinventando a roda com soluções frágeis. O Copybara oferece uma camada de abstração declarativa que é mais fácil de manter e versionar. Use git subtree para projetos pequenos com poucos repos e Copybara para fluxos corporativos complexos com transformações.

O diferencial real do Copybara e o feedback loop: além de empurrar código interno para o público, ele consegue puxar contribuições externas de volta ao monorepo, criando um ciclo completo de colaboração.

Pontos positivos e limitações

Entre os pontos positivos se destacam: configuração declarativa e versionavel, transformações poderosas sem scripts customizados, integração nativa com GitHub e Gerrit, e histórico de uso comprovado em produção pelo Google ha anos.

As limitações são reais e vale conhecer antes de adotar. A curva de aprendizado e moderada, especialmente para quem não conhece Starlark. A documentação oficial e funcional mas não e a mais amigável para iniciantes. O binário gerado pelo Bazel e grande e o tempo de compilação na primeira vez pode ser longo.

Outro ponto: o Copybara não e uma solução de monitoramento continuo nativamente. Você precisa integrar a execução em um pipeline de CI/CD como GitHub Actions ou Jenkins para ter sincronização automática a cada push.

Casos de uso reais

O Copybara serve bem para alguns perfis específicos de times e projetos:

  • Times com monorepo interno e repos públicos: empresas que desenvolvem em um monorepo privado e publicam bibliotecas open source conseguem manter os dois em sincronia sem processos manuais.
  • Fornecedores de SDK: quem distribui SDKs para clientes pode usar o Copybara para gerar versões públicas a partir do código interno, removendo automaticamente arquivos confidenciais.
  • Times de plataforma: ao padronizar bibliotecas internas, o time de plataforma pode propagar atualizações para repos de produto usando o Copybara de forma controlada.
  • Open source mantido por empresas: projetos como Bazel usam fluxos similares para aceitar contribuições externas e integra-las ao monorepo interno.

Dicas e boas práticas

Uma dica importante para iniciantes: comece com o modo SQUASH antes de tentar ITERATIVE. O SQUASH e mais simples de depurar e suficiente para a maioria dos casos de sincronização de bibliotecas.

Versione o arquivo copy.bara.sky junto com o código. Trate a configuração do Copybara como infraestrutura: qualquer mudança deve passar por code review antes de ir para produção. Use variáveis de ambiente para credenciais, nunca hardcode tokens no arquivo de configuração.

Para debug, o flag --dry-run e seu melhor amigo. Ele simula toda a execução sem escrever nada no repositório de destino, permitindo validar as transformações antes de aplicar de verdade.

Vale a pena?

Para times pequenos com um ou dois repositórios simples, provavelmente não vale a complexidade inicial. Scripts simples de git ou git subtree resolvem com menos overhead.

Mas se você trabalha em um ambiente corporativo com monorepo, múltiplos repos públicos ou precisa de sincronização recorrente com transformações, o Copybara e uma escolha solida. A confiabilidade e comprovada em escala Google e a ferramenta e ativamente mantida.

O próximo passo: clone o repositório no GitHub, leia os exemplos na pasta docs/ e monte uma configuração simples para um caso de uso real do seu projeto. A documentação tem vários exemplos prontos para adaptar.