As pessoas que você escolhe como proprietários do código devem ter permissões de gravação para o repositório. Quando o proprietário do código é uma equipe, essa equipe deverá ser visível e ter permissões de gravação, ainda que todos os membros individuais da equipe já tenham permissões de gravação diretamente, por meio da associação da organização ou por meio de outra associação à equipe.
Sobre os proprietários de código
Solicita-se automaticamente que os proprietários do código revisem quando alguém abre um pull request que modifica o código que possuem. Solicita-se automaticamente que os proprietários do código revejam os rascunhos de pull requests. Para obter mais informações sobre rascunhos de solicitações de pull, confira "Sobre solicitação de pull". Solicita-se automaticamente que os proprietários do código revejam os rascunhos de pull requests. Se você converter um pull request em rascunho, as pessoas que já assinaram as notificações não terão suas assinaturas canceladas automaticamente. Para obter mais informações, confira "Alterar o stage de uma pull request".
Quando alguém com permissões de administrador ou proprietário tiver habilitado revisões obrigatórias, se desejar, ele também poderá exigir aprovação de um proprietário do código para que o autor possa fazer merge de uma pull request no repositório. Para obter mais informações, confira "Sobre branches protegidos".
Se um arquivo tiver um proprietário do código, você poderá ver quem é o proprietário do código antes de abrir um pull request. No repositório, navegue até o arquivo e posicione o cursor sobre para ver uma dica de ferramenta com os detalhes da propriedade do código.
Local do arquivo CODEOWNERS
Para usar um arquivo CODEOWNERS, crie um arquivo chamado CODEOWNERS na raiz, em .github/ ou no diretório docs/ do repositório, no branch em que deseja adicionar os proprietários de código. Se arquivos CODEOWNERS existirem em mais de um desses locais, o GitHub os procurará nessa ordem e usará o primeiro que encontrar.
Cada arquivo CODEOWNERS atribui os proprietários do código para um único branch no repositório. Assim, você pode atribuir proprietários de código diferentes para diferentes branches, como @octo-org/codeowners-team para uma base de código no branch padrão e @octocat para um site do GitHub Pages no branch gh-pages.
Para que os proprietários do código recebam solicitações de revisão, o arquivo CODEOWNERS deve estar no branch base da pull request. Por exemplo, se você atribuir @octocat como o proprietário de código para arquivos .js no branch gh-pages do repositório, @octocat receberá solicitações de revisão quando uma solicitação de pull com alterações em arquivos .js for aberta entre o branch principal e gh-pages.
CODEOWNERS e forks
Para disparar solicitações de revisão, as solicitações de pull usam a versão de CODEOWNERS do branch base da solicitação de pull. O branch base é o que uma solicitação de pull modificará se a solicitação de pull for mesclada.
Se você criar uma solicitação de pull a partir de um fork e o branch base estiver no repositório upstream, a solicitação de pull usará o arquivo CODEOWNERS desse branch no repositório upstream. Se o branch base estiver dentro de seu fork, a solicitação de pull usará o arquivo CODEOWNERS desse branch em seu fork, mas isso só acionará solicitações de revisão se os proprietários de código forem adicionados ao fork especificamente com acesso write.
Quando você visualiza quem é responsável por um arquivo passando o mouse sobre , você verá informações CODEOWNERS do arquivo sobre qualquer branch em qualquer repositório que você esteja procurando.
Tamanho do arquivo CODEOWNERS
Os arquivos CODEOWNERS devem ter menos de 3 MB. Um arquivo CODEOWNERS acima deste limite não será carregado, o que significa que as informações do proprietário do código não serão mostradas e não será solicitado que os proprietários do código apropriado revise as alterações em um pull request.
Para reduzir o tamanho do seu arquivo CODEOWNERS, considere o uso de padrões curinga para consolidar múltiplas entradas em uma única entrada.
Sintaxe de CODEOWNERS
Aviso: existem algumas regras de sintaxe para arquivos gitignore que não funcionam em arquivos CODEOWNERS:
- Fazer o escape de um padrão que começa com
#usando\para que ele seja tratado como um padrão e não como um comentário não funciona - Usar
!para negar um padrão não funciona - Usar
[ ]para definir um intervalo de caracteres não funciona
Um arquivo CODEOWNERS usa um padrão que segue a maioria das mesmas regras usadas em arquivos gitignore. O padrão é seguido por um ou mais nomes de usuário ou nomes de equipes do GitHub usando o padrão @username ou o formato @org/team-name. Os usuários e as equipes precisam ter acesso write explícito ao repositório, mesmo se os membros da equipe já têm acesso.
Caso você deseje corresponder dois ou mais proprietários de código com o mesmo padrão, todos os proprietários de código precisam estar na mesma linha. Se os proprietários de código não estiverem na mesma linha, o padrão corresponderá apenas ao último proprietário de código mencionado.
Na maioria dos casos, você também pode se referir a um usuário por um endereço de email que tenha sido adicionado à conta dele, por exemplo, user@example.com. Não é possível usar um endereço de email para se referir a um conta de usuário gerenciada. Para obter mais informações sobre os contas de usuário gerenciadas, confira "Sobre os Enterprise Managed Users".
Os caminhos dos CODEOWNERS diferenciam maiúsculas de minúsculas, porque GitHub usa um sistema de arquivos que diferencia maiúsculas e minúsculas. Uma vez que os CODEOWNERS são avaliados por GitHub, até mesmo sistemas que diferenciam maiúsculas de minúsculas (por exemplo, macOS) devem usar caminhos e arquivos que são tratados corretamente no arquivo dos CODEOWNERS.
Se alguma linha do arquivo CODEOWNERS contiver uma sintaxe inválida, essa linha será ignorada. Ao navegar até o arquivo CODEOWNERS em seu repositório, você poderá ver todos os erros realçados. Uma lista de erros no arquivo CODEOWNERS de um repositório também pode ser acessada por meio da API. Para obter mais informações, confira "Pontos de extremidade da API REST para repositórios".
Se você especificar um usuário ou equipe que não existe ou tem acesso insuficiente, um proprietário de código não será atribuído.
Exemplo de um arquivo CODEOWNERS
# This is a comment.
# Each line is a file pattern followed by one or more owners.
# These owners will be the default owners for everything in
# the repo. Unless a later match takes precedence,
# @global-owner1 and @global-owner2 will be requested for
# review when someone opens a pull request.
* @global-owner1 @global-owner2
# Order is important; the last matching pattern takes the most
# precedence. When someone opens a pull request that only
# modifies JS files, only @js-owner and not the global
# owner(s) will be requested for a review.
*.js @js-owner #This is an inline comment.
# You can also use email addresses if you prefer. They'll be
# used to look up users just like we do for commit author
# emails.
*.go docs@example.com
# Teams can be specified as code owners as well. Teams should
# be identified in the format @org/team-name. Teams must have
# explicit write access to the repository. In this example,
# the octocats team in the octo-org organization owns all .txt files.
*.txt @octo-org/octocats
# In this example, @doctocat owns any files in the build/logs
# directory at the root of the repository and any of its
# subdirectories.
/build/logs/ @doctocat
# The `docs/*` pattern will match files like
# `docs/getting-started.md` but not further nested files like
# `docs/build-app/troubleshooting.md`.
docs/* docs@example.com
# In this example, @octocat owns any file in an apps directory
# anywhere in your repository.
apps/ @octocat
# In this example, @doctocat owns any file in the `/docs`
# directory in the root of your repository and any of its
# subdirectories.
/docs/ @doctocat
# In this example, any change inside the `/scripts` directory
# will require approval from @doctocat or @octocat.
/scripts/ @doctocat @octocat
# In this example, @octocat owns any file in a `/logs` directory such as
# `/build/logs`, `/scripts/logs`, and `/deeply/nested/logs`. Any changes
# in a `/logs` directory will require approval from @octocat.
**/logs @octocat
# In this example, @octocat owns any file in the `/apps`
# directory in the root of your repository except for the `/apps/github`
# subdirectory, as its owners are left empty. Without an owner, changes
# to `apps/github` can be made with the approval of any user who has
# write access to the repository.
/apps/ @octocat
/apps/github
# In this example, @octocat owns any file in the `/apps`
# directory in the root of your repository except for the `/apps/github`
# subdirectory, as this subdirectory has its own owner @doctocat
/apps/ @octocat
/apps/github @doctocat
Proteção de branch e de CODEOWNERS
Os proprietários do repositório podem atualizar regras de proteção de branch para garantir que o código alterado seja revisado pelos proprietários dos arquivos alterados. Edite sua regra de proteção de branch e habilite a opção "Exigir revisão dos proprietários do código". Para obter mais informações, confira "Sobre branches protegidos".
Observação: quando são necessárias revisões de proprietários de código, uma aprovação de qualquer um dos proprietários é suficiente para atender a esse requisito. Por exemplo, digamos que seu arquivo CODEOWNERS contenha a seguinte linha:
*.js @global-owner1 @global-owner2
Isso significa que as alterações nos arquivos JavaScript podem ser aprovadas por um @global-owner1 ou @global-owner2, mas as aprovações de ambos não são necessárias.
Para proteger totalmente um repositório contra alterações não autorizadas, você também precisa definir um proprietário para o próprio arquivo CODEOWNERS. O método mais seguro é definir um arquivo CODEOWNERS no diretório .github do repositório e definir o proprietário do repositório como o proprietário do arquivo CODEOWNERS (/.github/CODEOWNERS @owner_username) ou de todo o diretório (/.github/ @owner_username).
Como alternativa às regras de proteção de branch, você pode criar conjuntos de regras. Os conjuntos de regras têm algumas vantagens em relação às regras de proteção de branches, como status, e melhor capacidade de detecção sem exigir acesso de administrador. Você também pode aplicar vários conjuntos de regras ao mesmo tempo. Para obter mais informações, confira "Sobre os conjuntos de regras".