Revisões de Código Automáticas com CODEOWNERS

Um arquivo CODEOWNERS é um arquivo de texto simples no seu repositório que mapeia padrões de caminho para proprietários — usuários ou equipes do GitHub — e solicita automaticamente uma revisão desses proprietários sempre que um pull request modifica um caminho correspondente. Ele realiza duas funções simultaneamente: direciona as revisões para as pessoas certas sem que ninguém precise notificá-las manualmente, e documenta quem é responsável por quê. O problema é que o CODEOWNERS falha silenciosamente. Uma ordem incorreta de padrões, uma equipe sem membros ou um proprietário sem acesso de escrita não gera nenhuma mensagem de erro — a solicitação de revisão simplesmente não é disparada, e o PR é mesclado sem as revisões que você pretendia.

Este guia apresenta a configuração correta em poucos minutos e dedica a maior parte do tempo às armadilhas: a regra do último padrão vencedor, que silenciosamente substitui suas regras específicas, e as falhas de permissão, equipe vazia e branch padrão, que fazem o CODEOWNERS parecer configurado enquanto não faz nada.

O que faz um arquivo CODEOWNERS?

O CODEOWNERS designa indivíduos ou equipes responsáveis por caminhos específicos em um repositório. Quando alguém abre um pull request que modifica um caminho correspondente, o GitHub solicita automaticamente uma revisão dos proprietários listados. O mesmo formato de arquivo funciona no GitHub, GitLab e Bitbucket; os exemplos aqui são voltados principalmente para o GitHub.

Com uma parcela crescente de PRs criados por agentes de IA, uma regra CODEOWNERS em caminhos sensíveis — auth/, **/migrations/, configuração de CI — garante que um proprietário humano ainda revise as alterações do agente antes que elas sejam integradas.

Como configurar e aplicar o CODEOWNERS?

Coloque o arquivo em .github/CODEOWNERS. O GitHub procura em .github/, depois na raiz do repositório e, em seguida, em docs/, utilizando o primeiro CODEOWNERS encontrado. Por isso, um único local canônico evita confusões. Escreva uma regra por linha no formato padrão @proprietário e faça o commit no seu branch padrão.

# .github/CODEOWNERS
# Proprietários padrão para tudo no repositório
*                   @minha-org/core-team

# Frontend e backend por área
/src/frontend/      @minha-org/frontend-team
/src/backend/       @minha-org/backend-team

# Testes e documentação
**/tests/           @minha-org/qa-team
*.md                @minha-org/docs-team

# Caminhos sensíveis recebem um proprietário dedicado (coloque estes por último)
/src/auth/          @minha-org/security-team

Envie o arquivo como qualquer outro:

git add .github/CODEOWNERS
git commit -m "Add CODEOWNERS"
git push origin main

Fazer o commit do arquivo apenas solicita revisores — não bloqueia nada. Para realmente controlar as mesclagens, habilite duas configurações em conjunto: Require a pull request before merging e Require review from Code Owners. Você pode defini-las nos Rulesets mais recentes (Settings → Rules → Rulesets) ou em uma regra de proteção de branch clássica (Settings → Branches). Ambas as opções estão disponíveis; os rulesets são a abordagem mais recente.

Padrões de sintaxe do CODEOWNERS que vale conhecer

A linguagem de padrões segue a maioria das regras do gitignore. Estes cinco cobrem praticamente tudo:

*                   @core-team      # padrão global
/api/               @backend-team   # um diretório
*.ts                @frontend-team  # uma extensão, em qualquer profundidade
**/tests/           @qa-team        # diretório aninhado em qualquer lugar
/security/          @sec-team @compliance-team   # dois proprietários, uma linha

Um glob de extensão não ancorado como *.ts corresponde a arquivos desse tipo em qualquer lugar do repositório — comporta-se da mesma forma que **/*.ts. Uma regra importante ao listar vários proprietários: todos devem estar na mesma linha. Se você os dividir em linhas separadas, o padrão corresponderá apenas ao último proprietário mencionado. Quando a revisão de proprietários de código é obrigatória, a aprovação de qualquer um dos proprietários listados satisfaz o requisito.

Um mito a desfazer: ao contrário do .gitignore, o CODEOWNERS do GitHub não suporta negação com !. Padrões como !README.md são rejeitados como inválidos — a própria documentação do GitHub lista !, intervalos de caracteres [ ] e o escape \# como recursos do gitignore que não funcionam aqui. Para excluir um caminho, atribua-lhe um proprietário diferente ou organize as regras de forma que nenhuma o corresponda (deixar a coluna de proprietário vazia em uma linha posterior e mais específica remove a propriedade daquele caminho).

A regra do último padrão vencedor (o erro nº 1)

O CODEOWNERS segue a regra do último padrão vencedor: quando vários padrões correspondem a um arquivo, apenas a última linha correspondente atribui proprietários. A ordem é a causa mais comum de falhas. Coloque regras gerais no topo e substituições específicas no final.

Veja a ordem incorreta — o padrão curinga fica por último e silenciosamente reivindica tudo:

# ERRADO — * é o último padrão correspondente, então @core-team também é dono de /src/auth/
/src/auth/          @security-team
*                   @core-team

Como * corresponde a /src/auth/app.ts e aparece mais tarde no arquivo, @security-team nunca é solicitado. Inverta a ordem:

# CORRETO — geral primeiro, substituição específica por último
*                   @core-team
/src/auth/          @security-team

Agora, uma alteração em /src/auth/ solicita @security-team, e todo o resto recai sobre @core-team. Revise a ordem dos padrões sempre que adicionar uma nova regra.

Por que o CODEOWNERS silenciosamente não dispara

A maioria dos relatos de “está configurado, mas nada acontece” tem origem em um destes casos. O CODEOWNERS é lido a partir do branch base do pull request, diferencia maiúsculas de minúsculas, deve ter menos de 3 MB e ignora qualquer linha com sintaxe inválida — portanto, um arquivo que parece correto pode não disparar nenhuma revisão.

Dois detalhes de permissão causam a maioria das falhas silenciosas. As pessoas que você escolhe como proprietários de código devem ter permissões de escrita — um proprietário sem acesso de escrita é silenciosamente ignorado. E quando o proprietário é uma equipe, ela própria deve ser visível e ter acesso de escrita, mesmo que todos os seus membros já o possuam individualmente. Se você nomear um usuário ou equipe que não existe ou não tem acesso, nenhum proprietário de código é atribuído — sem qualquer aviso no PR. O GitHub exibe linhas problemáticas: abra o arquivo CODEOWNERS na interface do repositório para ver os erros destacados, que também estão disponíveis pela API REST.

Além da atribuição estática: auto-atribuição de equipes e Actions

O CODEOWNERS mapeia caminhos para proprietários de forma estática. Dois mecanismos o complementam quando isso não é suficiente.

A auto-atribuição de equipes nativa evita que você notifique uma equipe inteira. Em Organization → Teams → equipe → Settings → Code review, habilite a auto-atribuição: sempre que a equipe for solicitada, a solicitação para a equipe inteira é removida e um subconjunto de membros é atribuído em seu lugar. Escolha round robin, que rotaciona pela solicitação menos recente, ou load balance, que equilibra o total de solicitações recentes de cada membro. Observe uma interação importante: quando um proprietário de código é exigido por proteção de branch, a solicitação para a equipe não pode ser removida, então a solicitação individual aparece em adição à da equipe.

Recorra ao GitHub Actions apenas quando a atribuição precisar depender do diff ou de um label — algo que o CODEOWNERS não consegue expressar. Um workflow mínimo usando actions/checkout (versão mais recente v7.0.0, lançada em 18 de junho de 2026) com uma action de atribuição de revisores no gatilho simples pull_request:

name: Assign Reviewers
on:
  pull_request:
    types: [opened, ready_for_review]
permissions:
  pull-requests: write
jobs:
  assign:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0   # necessário para git diff entre branches
      # ...mapeie caminhos alterados ou labels para revisores aqui

Use a hierarquia de escalada como uma decisão, não como um menu: CODEOWNERS para regras estáticas de caminho→proprietário, auto-atribuição de equipe para distribuir a carga dentro de uma equipe, Actions para lógica baseada em alterações ou labels.

Comece com um único .github/CODEOWNERS no seu branch padrão, ordene-o do geral para o específico, habilite “Require review from Code Owners” e então abra um PR de teste para confirmar que o proprietário esperado é solicitado — essa única verificação detecta as falhas silenciosas antes que cheguem à produção.

Perguntas Frequentes

Qual é a diferença entre CODEOWNERS e a auto-atribuição de revisão de código de equipes do GitHub?

O CODEOWNERS é um arquivo estático que mapeia padrões de caminho para proprietários e solicita revisão sempre que um PR modifica um caminho correspondente. A auto-atribuição de equipe é uma configuração organizacional que, quando uma equipe é solicitada, substitui a solicitação para a equipe inteira por um subconjunto de membros escolhidos por round robin ou load balance. Eles funcionam em conjunto: o CODEOWNERS decide qual equipe é responsável por um caminho, e a auto-atribuição decide quais membros dessa equipe serão efetivamente notificados.

Posso excluir um arquivo específico de uma regra CODEOWNERS usando negação como no gitignore?

Não. O CODEOWNERS do GitHub não suporta negação, portanto um padrão como '!README.md' é rejeitado como inválido e a linha é silenciosamente ignorada. A documentação do GitHub lista a negação com '!', intervalos de caracteres '[ ]' e o escape '#' como recursos do gitignore que não funcionam aqui. Para excluir um caminho, adicione uma regra posterior e mais específica atribuindo-lhe um proprietário diferente, ou deixe a coluna de proprietário vazia nessa linha específica para remover a propriedade.

Por que os proprietários de código não estão sendo solicitados no meu pull request, mesmo que o arquivo pareça correto?

A causa mais comum é que o CODEOWNERS é lido a partir do branch base do PR — portanto, um arquivo presente apenas no seu branch de funcionalidade nunca dispara. Outras causas silenciosas incluem: proprietário sem acesso de escrita, equipe proprietária que não é visível ou não tem acesso de escrita, equipe vazia, PR em modo rascunho (que nunca dispara solicitações de proprietários de código), arquivo acima de 3 MB, caminhos com capitalização incorreta ou uma linha inválida que o GitHub ignora sem aviso.

O CODEOWNERS bloqueia mesclagens por conta própria, ou preciso de proteção de branch?

O CODEOWNERS por si só apenas solicita revisores; ele nunca bloqueia uma mesclagem. Para controlar as mesclagens, você também deve habilitar duas configurações em conjunto: 'Require a pull request before merging' e 'Require review from Code Owners'. Configure-as em um ruleset em Settings, Rules, Rulesets, ou em uma regra de proteção de branch clássica em Settings, Branches. Ambas as opções estão disponíveis, sendo os rulesets a abordagem mais recente.