Criar conjuntos de regras para um repositório

Introdução

Você pode criar conjuntos de regras para controlar como os usuários podem interagir com as tags e os branches selecionados em um repositório. Você pode controlar ações como quem pode efetuar push de commits para determinado branch e como os commits precisam ser formatados ou quem pode excluir ou renomear uma tag. Você também pode impedir que as pessoas renomeiem repositórios.

Ao criar um conjunto de regras, você pode permitir que alguns usuários ignorem as regras do conjunto de regras.

Para obter mais informações sobre conjuntos de regras, confira Sobre os conjuntos de regras.

Para clientes com os planos GitHub Team e GitHub Enterprise, você também pode criar conjuntos de regras para os repositórios em uma organização. Para saber mais, confira Criar conjuntos de regras para repositórios na sua organização.

Como usar a sintaxe fnmatch

É possível usar a sintaxe fnmatch para definir padrões de destino ao criar um conjunto de regras.

Use o curinga * para encontrar a correspondência de qualquer cadeia de caracteres. Como o GitHub usa o sinalizador File::FNM_PATHNAME para a sintaxe File.fnmatch, o curinga * não corresponde aos separadores de diretório (/). Por exemplo, qa/* corresponderá a todos os branches que começam com qa/ e que contêm uma barra "/", mas não corresponderá a qa/foo/bar. Você pode incluir qualquer quantidade de barras "/" após qa com qa/**/*, o que corresponderá, por exemplo, a qa/foo/bar/foobar/hello-world. Você também pode estender a cadeia de caracteres qa com qa**/**/* para tornar a regra mais inclusiva.

Para obter mais informações sobre as opções de sintaxe, confira a documentação de fnmatch.

Sintaxe de fnmatch sem suporte

Não há suporte para todas as expressões da sintaxe fnmatch nas regras de proteção do branch. Esteja ciente das seguintes restrições:

• Não é possível usar a barra invertida (\) como um caractere de citação, pois o GitHub não é compatível com o uso de barras invertidas nas regras de proteção de ramificação.
• Você pode especificar conjuntos de caracteres entre colchetes ([]), mas atualmente não pode complementar um conjunto com o operador ^ (por exemplo, [^charset]).
• Embora o GitHub seja compatível com File::FNM_PATHNAME na sintaxe fnmatch, File::FNM_EXTGLOB não é compatível.

Como usar expressões regulares para metadados de commit

Ao adicionar restrições de metadados para um conjunto de regras que tem como meta branches ou tags, use a sintaxe de expressão regular para definir a quais padrões os metadados relevantes, como a mensagem do commit ou o nome do branch ou da tag, precisam ou não corresponder.

Por padrão, as restrições de metadados não aceitam padrões regex. Para habilitar isso, selecione Precisa corresponder a um determinado padrão de regex ao criar as restrições de metadados para o conjunto de regras.

Os conjuntos de regras dão suporte à sintaxe RE2. Para obter mais informações, confira o guia de sintaxe do Google. Para validar as expressões, use o validador em regex101.com selecionando a variante "Golang" na barra lateral esquerda.

Por padrão, expressões regulares em restrições de metadados não consideram várias linhas de texto. Por exemplo, se você tiver uma mensagem do commit de várias linhas, o padrão ^ABC será uma correspondência se qualquer linha da mensagem começar com ABC. Para corresponder a várias linhas da mensagem, comece sua expressão com (?m).

Não há suporte para a declaração lookahead negativa, indicada como ?!. No entanto, para os casos em que você precisa procurar determinada cadeia de caracteres que não é seguida de outra cadeia de caracteres especificada, use a asserção lookahead positiva, indicada como ?, combinada com o requisito "Não deve corresponder a determinado padrão regex".

Padrões úteis de expressão regular

Os exemplos a seguir fornecem padrões úteis para metadados de commit. Para usar esses padrões, defina Requisito como "Precisa corresponder a um determinado padrão de regex".

Garantir que os nomes de branches sejam compatíveis com o Windows

Use o padrão a seguir para garantir que os nomes dos branches incluam apenas números, letras minúsculas e os caracteres - e _. Isso garante que os nomes dos branches sejam compatíveis com sistemas operacionais que não usam sistemas de arquivos que diferenciam maiúsculas de minúsculas por padrão.

\A[0-9a-z-_]$

\A[0-9a-z-_]$

Corresponde a: my-branch

Não corresponde: myBranch

Garantir que os nomes de tags usem um controle de versão semântico

Use o padrão a seguir para garantir que os nomes das tags estejam em conformidade com o controle de versão semântico. Para obter mais informações, confira a documentação em semver.org.

^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$

^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$

Corresponde a: 1.2.3, 10.20.30 e 1.1.2-prerelease+meta

Não corresponde: 1.2, 1.2-SNAPSHOT

Limitar o comprimento das linhas em mensagens de commit

O livro Pro Git recomenda limitar a primeira linha de uma mensagem de commit a cerca de 50 caracteres.

Use o padrão a seguir para garantir que a primeira linha em uma mensagem de commit contenha 50 caracteres ou menos.

\A.{1,50}$

\A.{1,50}$

Garantir que as mensagens do commit comecem com uma resolução e um número de problema

Use o padrão a seguir para garantir que as mensagens de commit contenham a palavra Resolves: ou Fixes:, seguido de uma cadeia de caracteres como #1234.

^(Resolves|Fixes): \#[0-9]+$

^(Resolves|Fixes): \#[0-9]+$

Corresponde a: Fixes: #1234

Não corresponde: Add conditional logic to foo.bar

Impor commits convencionais

Use o padrão a seguir para garantir que as mensagens de commit estejam em conformidade com a especificação Commits Convencionais. Para obter mais informações, confira conventionalcommits.org.

^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test){1}(\([\w\-\.]+\))?(!)?: ([\w ])+([\s\S]*)

^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test){1}(\([\w\-\.]+\))?(!)?: ([\w ])+([\s\S]*)

Corresponde a: feat: allow provided config object to extend other configs

Não corresponde: Add conditional logic to foo.bar

Usar status de imposição de conjunto de regras

Ao criar ou editar seu conjunto de regras, você pode usar status de imposição para configurar como seu conjunto de regras será imposto.

Você pode selecionar qualquer um dos seguintes status de imposição para seu conjunto de regras.

• Active: seu conjunto de regras será imposto após a criação.
• Evaluate: seu conjunto de regras não será aplicado, mas você poderá monitorar quais ações violariam ou não as regras na página "Insights de regras".
• Disabled: seu conjunto de regras não será imposto ou avaliado.

Usar o modo "Avaliar" é uma ótima opção para testar seu conjunto de regras sem impô-lo. É possível usar a página "Insights da regra" para ver se a contribuição teria violado a regra. Para saber mais, confira Gerenciar conjuntos de regras para um repositório.

Criar um conjunto de regras de branch ou tag

1. Em GitHub, acesse a página principal do repositório.

2. Abaixo do nome do repositório, clique em Configurações. Caso não consiga ver a guia "Configurações", selecione o menu suspenso , clique em Configurações.

   

3. Na barra lateral esquerda, em "Código e automação", clique em Regras e em Conjuntos de regras.

   

4. Você pode criar um conjunto de regras direcionado a branches ou a tags.

   • Para criar um conjunto de regras direcionado a branches, clique em Novo conjunto de regras de branch.

   • Para criar um conjunto de regras direcionado a tags, selecione e clique em Novo conjunto de regras de tag.

     

5. Em "Nome do conjunto de regras", digite um nome para o conjunto de regras.

6. Opcionalmente, para alterar o status de imposição padrão, clique em Desabilitado e selecione um status de imposição. Para obter mais informações sobre os status de imposição, confira Sobre os conjuntos de regras.

Conceder permissões de bypass para o conjunto de regras de branch ou tag

Você pode conceder a determinadas funções, equipes ou aplicativos permissões de bypass para seu conjunto de regras. Os seguintes são qualificados para acesso de bypass:

• Administradores de repositório, proprietários da organização e proprietários corporativos
• A função de manutenção ou gravação ou funções de repositório personalizadas com base na função de gravação
• Equipes, excluindo equipes secretas. Confira Sobre equipes.
• Chaves de implantação
• GitHub Apps
• Dependabot. Para obter mais informações sobre o Dependabot, confira Guia de início rápido do Dependabot.

1. Para conceder permissões de bypass para o conjunto de regras, na seção "Bypass list", clique em Add bypass.

2. Na caixa de diálogo modal "Adicionar bypass" exibida, procure a função, a equipe ou o aplicativo ao qual você deseja conceder permissões de bypass, selecione a função, a equipe ou o aplicativo na seção "Sugestões" e clique em Adicionar selecionados.

3. Opcionalmente, para conceder bypass a um ator sem permitir que ele envie diretamente para um repositório, à direita de "Sempre permitir", clique em e, em seguida, clique em Somente para pull requests.

   O ator selecionado agora é obrigado a abrir uma pull request para fazer alterações em um repositório, criando uma trilha digital clara com suas alterações no pull request e no log de auditoria. Em seguida, o ator pode optar por ignorar quaisquer proteções de branch e mesclar essa pull request.

Escolher quais branches ou tags direcionar

Para direcionar branches ou tags na seção "Branches de destino" ou "Tags de destino", selecione Adicionar um destino e escolha como deseja incluir ou excluir branches ou tags. Use a sintaxe fnmatch para incluir ou excluir branches ou tags com base em um padrão. Para obter mais informações, confira Como usar a sintaxe de fnmatch.

Você pode adicionar vários critérios de direcionamento ao mesmo conjunto de regras. Por exemplo, você pode incluir o branch padrão, incluir os branches que correspondam ao padrão *feature* e excluir especificamente um branch que corresponda ao padrão not-a-feature.

Selecionar proteções de branch ou tag

Na seção "Proteções de branch" ou "Proteções de tag", selecione as regras que deseja incluir no conjunto de regras. Ao selecionar uma regra, você poderá inserir configurações adicionais para ela. Para obter mais informações sobre as regras, confira Regras disponíveis para conjuntos de regras.

Adicionar restrições de metadados

As restrições de metadados devem se destinar a aumentar a consistência entre os commits no seu repositório. Elas não se destinam a substituir medidas de segurança, como exigir uma revisão de código por meio de solicitações de pull.

1. Para adicionar uma regra para controlar metadados de commit ou nomes de branches, na seção “Restrições” ao criar ou editar um conjunto de regras, selecione Restringir metadados de commit ou Restringir nomes de branches.

2. Defina as configurações para a restrição e, em seguida, clique em Adicionar. Você pode adicionar várias restrições ao mesmo conjunto de regras.

3. Para corresponder a um determinado padrão regex, na lista suspensa "Requisito", selecione Deve corresponder a um determinado padrão regex.

   Para a maioria dos requisitos, como "Precisa começar com um padrão correspondente", o padrão inserido é interpretado literalmente e não há suporte para curingas. Por exemplo, o caractere * representa apenas o caractere literal *.

   Para padrões mais complexos, você pode selecionar "Precisa corresponder a determinado padrão regex" ou "Não precisa corresponder a determinado padrão regex" e usar a sintaxe de expressão regular para definir o padrão correspondente. Para obter mais informações, confira Sobre expressões regulares para metadados de commit" na documentação GitHub Enterprise Cloud.

   Qualquer pessoa que visualizar os conjuntos de regras de um repositório poderá ver a descrição fornecida por você.

4. Opcionalmente, antes de aplicar o conjunto de regras com as restrições de metadados, escolha o status de imposição “Avaliar” para o conjunto de regras, a fim de testar os efeitos de todas as restrições de metadados sem afetar os colaboradores. Para obter mais informações sobre as restrições de metadados, confira Regras disponíveis para conjuntos de regras.

Finalizar o conjunto de regras de branch ou tag e próximas etapas

Para concluir a criação do conjunto de regras, clique em Criar. Se o status de imposição do conjunto de regras for definido como "Ativo", o conjunto de regras entrará em vigor imediatamente.

Você pode exibir insights para o conjunto de regras para ver como as regras estão afetando seus colaboradores. Se o status de imposição estiver definido como "Avaliar", você poderá ver quais ações teriam passado ou falhado se o conjunto de regras estivesse ativo. Para obter mais informações sobre insights para conjuntos de regras, confira Gerenciar conjuntos de regras para um repositório.