Resumo

  • CODEOWNERS é uma regra de roteamento por caminho e por ramo; o GitHub pode pedir automaticamente revisão aos proprietários quando uma pull request não marcada como rascunho altera código de sua responsabilidade.
  • O resultado depende do arquivo no ramo-base, da precedência de localização, do último padrão correspondente, dos caminhos modificados e da elegibilidade dos proprietários. Um arquivo visto agora não certifica um resultado anterior.
  • Um comprovante de revisão deve manter distintos a configuração aplicável, o diff, a solicitação, a resposta de revisão e as demais condições de merge.

Uma configuração não substitui a história

“Os donos revisaram” pode parecer uma frase suficiente, mas mistura perguntas diferentes. Qual era o ramo-base? Quais arquivos realmente mudaram? Qual padrão ganhou? Os usuários ou a equipe nomeados tinham acesso adequado naquele momento? Houve pedido e depois uma resposta que cobria aquele diff? E a aprovação de proprietário era de fato exigida? Um arquivo no navegador raramente fornece a sequência inteira.

O GitHub define CODEOWNERS como um arquivo para apontar pessoas ou equipes responsáveis pelo código de um repositório. Quando uma pull request que não é rascunho modifica código possuído, o GitHub solicita automaticamente revisão aos proprietários aplicáveis. Rascunhos não recebem esse pedido automático antes de ficarem prontos para revisão. O mecanismo encaminha atenção técnica; não afirma que essa atenção se converteu em uma decisão.

O ramo é parte da regra. Cada arquivo CODEOWNERS atribui proprietários a um único ramo, e os pedidos de revisão usam a versão do ramo-base da pull request. Em uma contribuição de fork para um repositório ascendente, vale o arquivo do ramo-base ascendente. Assim, um mesmo patch pode apontar para proprietários diferentes se tiver como destino main ou um ramo de manutenção. O arquivo da cabeça, ou a versão exibida mais tarde no ramo padrão, não prova a política que governou o pedido anterior.

Também existe precedência de localização: o GitHub busca .github/, a raiz e docs/, nessa ordem, e usa o primeiro arquivo encontrado. Um arquivo maior que três megabytes não é carregado; nesse caso, a propriedade não aparece e os donos apropriados não recebem pedidos. Ter uma política escrita não basta para provar que ela foi a política operacional de uma ocorrência.

O último padrão pode mudar quem responde

As linhas de um arquivo podem sugerir soma de responsabilidades, mas o GitHub dá prioridade ao último padrão que corresponde. Uma regra geral * pode ser substituída, para uma alteração JavaScript, por uma linha posterior *.js. Proprietários na mesma linha compartilham o padrão; proprietários distribuídos em linhas correspondentes diferentes não necessariamente se acumulam. Sem reconstruir a ordem e os caminhos do diff, uma explicação pode atribuir a revisão a quem não seria solicitado.

O arquivo possui ainda condições de validade. Caminhos são sensíveis a maiúsculas e minúsculas. Uma linha inválida é ignorada. Um usuário ou equipe inexistente, ou sem acesso suficiente, não é atribuído. Isso não acusa nenhum repositório específico. Apenas impede que uma política estática seja apresentada como recibo automático de uma ação.

O próprio GitHub aconselha definir um proprietário para o arquivo CODEOWNERS. A orientação expõe uma questão de governança: a regra que distribui responsabilidade precisa ter sua própria via de alteração observável. Caso contrário, o leitor sabe quem supostamente protege o código, mas não quem poderia mudar a regra de proteção.

Pedido, aprovação e merge não se fundem

O GitHub separa o pedido automático de revisão da configuração opcional que exige aprovação de um code owner antes do merge. Essa exigência é ativada separadamente por administradores ou proprietários. Quando vários donos estão no mesmo padrão, a aprovação de um deles pode satisfazer a condição. O arquivo, por si, não transforma todos os nomes em um bloqueio obrigatório.

Há ainda controles que se combinam. Rulesets e proteção de ramo podem operar juntos; as regras aplicáveis são agregadas e a versão mais restritiva prevalece quando a mesma regra aparece de formas diferentes. Exigência de pull request, quantidade de aprovações, checks de status, implantação bem-sucedida, comentários resolvidos, método de merge e permissões de bypass podem ser superfícies autônomas. O GitHub observa que uma pull request com todas as revisões exigidas pode continuar bloqueada se outra pull request no mesmo commit de cabeça tiver uma revisão pendente ou rejeitada.

Uma aprovação continua a ser um sinal valioso de que mudanças parecem prontas para merge. Ela não é, contudo, uma certidão de que o arquivo foi resolvido conforme alegado e de que cada porta posterior já foi aberta.

Um recibo de configuração para revisão

Uma afirmação consequente deve preservar o identificador da pull request, as referências de base e cabeça e o conjunto de caminhos alterados. Deve guardar também a localização e a identidade de conteúdo do CODEOWNERS aplicável no ramo-base, o padrão vencedor e os proprietários resolvidos. Depois vêm os eventos: pedido de revisão, resposta, data e diff ou commit coberto.

Se a afirmação alcança a possibilidade de merge, deve apontar separadamente os rulesets ou proteções aplicáveis, os estados observados de cada condição e qualquer bypass documentado. Quando uma ligação não está comprovada, o relato deve parar ali. Esse recibo é uma disciplina editorial: não cria uma exigência nova no GitHub nem troca os controles existentes por uma narrativa.

Fontes

  1. GitHub Docs — About code owners
  2. GitHub Docs — Pull request reviews
  3. GitHub Docs — About rulesets
  4. GitHub Docs — Available rules for rulesets