É possível criar conjuntos de regras para branch ou tags para controlar como os usuários podem interagir com as tags e os branches selecionados em um repositório.
Ao criar um conjunto de regras, você pode permitir que alguns usuários ignorem as regras do conjunto de regras. Podem ser usuários com determinadas funções, equipes específicas ou GitHub Apps.
Para obter mais informações sobre como criar conjuntos de regras e permissões de bypass, confira Criar conjuntos de regras para um repositório.
Restringir as criações
Se isso estiver selecionado, somente os usuários com permissões de bypass poderão criar branches ou tags cujos nomes correspondam ao padrão especificado.
Restringir as atualizações
Se isso estiver selecionado, somente os usuários com permissões de bypass poderão enviar por push para branches ou tags cujos nomes correspondam ao padrão especificado.
Restringir as exclusões
Se isso estiver selecionado, somente os usuários com permissões de bypass poderão excluir branches ou tags cujos nomes correspondam ao padrão especificado. Essa regra está selecionada por padrão.
Exigir histórico linear
A imposição de um histórico de commits linear impede que os colaboradores efetuem push de commits de mesclagem em tags e branches direcionados. Nesse caso, qualquer solicitação de pull mesclada no branch ou na tag precisa usar uma mesclagem squash ou uma mesclagem de troca de base. Um histórico de commit estritamente linear pode ajudar as equipes a reverter alterações mais facilmente. Para obter mais informações sobre métodos de mesclagem, confira Sobre merges de pull request.
Antes de exigir um histórico de commit linear, seu repositório deve permitir merge squash ou merge rebase. Para saber mais, confira Configurar merges de pull request.
Exigir que as implantações tenham êxito antes da mesclagem
Note
Essa regra não está disponível para conjuntos de regras criados no nível da organização.
Você pode exigir que as alterações sejam implantadas com sucesso em ambientes específicos antes que um branch possa ser mesclado. Por exemplo, você pode usar essa regra para garantir que as alterações sejam implantadas com sucesso em um ambiente de preparo antes que as alterações sejam mescladas com o branch padrão.
Exigir commits assinados
Quando você habilitar a assinatura de commit obrigatória em um branch, os colaboradores só poderão efetuar push de commits que foram assinados e verificados no branch. Para saber mais, confira Sobre a verificação de assinatura de commit.
Quando você cria um branch, as regras e os conjuntos de regras de proteção de branch se comportam de maneira diferente: com conjuntos de regras, verificamos apenas os commits que não são acessíveis diretamente de outros branches. Por outro lado, com as regras de proteção de branch, não verificamos commits assinados a menos que você restrinja as transmissões que criem branches correspondentes. Para ambos, quando você atualizar uma ramificação, ainda verificaremos todos os commits no intervalo especificado, mesmo que um commit possa ser acessado de outras ramificações.
Em ambos os métodos, usamos a verified_signature? para confirmar se um commit tem uma assinatura válida. Caso contrário, a atualização não será aceita.
Note
Se um colaborador fizer push de um commit não assinado para um branch que exige assinaturas de commit, o colaborador deverá fazer rebase do commit para incluir uma assinatura verificada e, em seguida, fazer push forçado no commit reescrito para o branch.
Você sempre pode fazer push de commits locais para o branch se os commits forem assinados e verificados. No entanto, você não pode mesclar as pull requests no branch no GitHub Enterprise Server. Você pode mesclar as pull requests localmente. Para saber mais, confira Fazer checkout de pull requests no local.
Exigir uma solicitação de pull antes da mesclagem
Você pode exigir que todas as alterações no branch de destino sejam associadas a uma solicitação de pull. A solicitação de pull não precisa necessariamente ser aprovada, mas precisa ser aberta.
Configurações adicionais
Note
Se você selecionar Ignorar aprovações de pull request obsoletas quando novas confirmações forem transmitidos e/ou Exigir aprovação do push revisável mais recente, a criação manual do commit de mesclagem de uma pull request e sua transmissão direta em um branch protegido apresentará falha, a menos que o conteúdo da mesclagem corresponda exatamente à mesclagem gerada por GitHub para a pull request.
Além disso, com essas configurações, a aprovação de revisões será ignorada como obsoleta se a base de mesclagem introduzir novas alterações depois que a revisão for enviada. A base de mesclagem é o commit que é o último ancestral comum entre o branch do tópico e o branch base. Se a base de mesclagem for alterada, a solicitação de pull não poderá ser mesclada até que alguém aprove o trabalho novamente.
Os administradores do repositório ou funções personalizadas com a permissão "editar regras do repositório" podem exigir que todas as solicitações de pull recebam um número específico de revisões de aprovação antes que alguém mescle a solicitação de pull em um branch protegido. Você pode exigir a aprovação de revisões de pessoas com permissões de gravação no repositório ou de um proprietário de código designado.
Se você habilitar as revisões obrigatórias, os colaboradores só poderão efetuar push das alterações em um branch por meio de uma solicitação de pull aprovada pelo número obrigatório de revisores com permissões de gravação.
Se alguém escolher a opção Solicitar alterações em uma revisão, ela precisará aprovar a solicitação de pull para que a solicitação de pull possa ser mesclada. Se um revisor que solicita alterações em um pull request não estiver disponível, qualquer pessoa com permissões de gravação no repositório poderá ignorar a revisão de bloqueio.
Mesmo depois de todos os revisores necessários terem aprovado um pull request, os colaboradores não poderão fazer o merge do pull request se houver outros pull requests abertos que tenham um branch de cabeçalho apontando para o mesmo commit com revisões pendentes ou rejeitadas. Alguém com permissões de gravação deve aprovar ou ignorar a revisão de bloqueio nos outros pull requests primeiro.
Opcionalmente, você pode optar por ignorar as aprovações obsoletas de solicitação de pull quando é efetuado o push de commits que afetam a comparação na solicitação de pull. O GitHub registra o estado da comparação no ponto em que uma solicitação de pull é aprovada. Esse estado representa o conjunto de alterações que o revisor aprovou. Se a comparação mudar desse estado (por exemplo, porque um colaborador efetua push de novas alterações para o branch de solicitação de pull ou clica em Atualizar branch ou porque uma solicitação de pull relacionada foi mesclada no branch de destino), a revisão de aprovação será descartada como obsoleta e a solicitação de pull não poderá ser mesclada até que alguém aprove o trabalho novamente. Para obter informações sobre o branch de destino, confira Sobre solicitação de pull.
Opcionalmente, você pode optar por exigir análises dos proprietários do código. Se você fizer isso, qualquer solicitação de pull que modifica o conteúdo com um proprietário do código precisará ser aprovada pelo proprietário desse código para que a solicitação de pull possa ser mesclada no branch protegido. Observe que, se o código tiver vários proprietários, uma aprovação de qualquer um dos proprietários de código será suficiente para atender a esse requisito. Para saber mais, confira Sobre os proprietários de código.
Opcionalmente, você pode exigir uma aprovação de alguém que não seja a última pessoa a efetuar push para um branch para que uma solicitação de pull possa ser mesclada. Isso representa que pelo menos um outro revisor autorizado aprovou alguma alteração. Por exemplo, o "último revisor" pode verificar se o conjunto mais recente de alterações incorpora os comentários de outras revisões e não adiciona um conteúdo novo e não revisado.
Para pull requests complexas que exigem muitas revisões, exigir uma aprovação de alguém que não seja a última pessoa a efetuar o push pode ser um meio-termo que evita a necessidade de ignorar todas as revisões obsoletas: com essa opção, as revisões "obsoletas" não são ignoradas e a pull request permanece aprovada desde que alguém que não seja a pessoa que fez as alterações mais recentes a aprove. Os usuários que já revisaram uma solicitação de pull podem reaprová-la após o push mais recente para atender a esse requisito. Se você tiver preocupações com o "sequestro" de pull requests (em que um conteúdo não aprovado é adicionado às pull requests aprovadas), será mais seguro ignorar as revisões obsoletas.
Opcionalmente, você pode exigir que todos os comentários na solicitação de pull sejam resolvidos para que ela seja mesclada em um branch. Isso garante que todos os comentários sejam resolvidos ou reconhecidos antes do merge.
Exigir a aprovação nas verificações de status antes da mesclagem
As verificações de status obrigatórias garantem a aprovação em todos os testes de CI para que os colaboradores façam alterações em uma tag ou em um branch direcionado pelo seu conjunto de regras. As verificações de status obrigatórias podem ser verificações ou status. Para saber mais, confira Sobre verificações de status.
Use a API de status de commits para permitir que os serviços externos marquem os commits com um status apropriado. Para saber mais, confira Pontos de extremidade da API REST para status de commits.
Após a habilitação das verificações de status obrigatórias, todas as verificações de status obrigatórias precisarão ser aprovadas para que os colaboradores possam mesclar as alterações na tag ou no branch protegido.
Qualquer pessoa ou integração com permissões de gravação em um repositório pode definir o estado de qualquer verificação de status no repositório, mas em alguns casos você só pode aceitar uma verificação de status de um GitHub App específico. Ao adicionar uma regra de verificação de status obrigatória, você pode selecionar um aplicativo como a fonte esperada de atualizações de status. O aplicativo precisa ser instalado no repositório com a permissão statuses:write, precisa ter enviado uma execução de verificação recentemente e precisa estar associado a uma verificação de status obrigatória preexistente no conjunto de regras. Se o status for definido por qualquer outra pessoa ou integração, a mesclagem não será permitida. Se você selecionar "qualquer fonte", você ainda pode verificar manualmente o autor de cada status, listado na caixa de merge.
Note
Para verificações de status em nível de organização, o aplicativo deve ser instalado com a permissão statuses:write. Somente aplicativos com essa permissão são exibidos ao configurar conjuntos de regras no nível da organização.
Você pode considerar as verificações de status obrigatórias como sendo "flexíveis" ou "estritas". O tipo de verificação de status obrigatória que você escolher determinará se o branch precisará ser atualizado com o branch base antes do merge.
| Tipo de verificação de status obrigatória | Configuração | Requisitos de merge | Considerações |
|---|---|---|---|
| Rigoroso | A caixa de seleção Exigir a atualização dos branches antes da mesclagem está marcada. | O branch do tópico precisa estar atualizado com o branch base antes da mesclagem. | Este é o comportamento padrão para verificações de status obrigatórias. Podem ser necessários mais builds, pois você precisará atualizar o branch principal depois que outros colaboradores atualizarem o branch de destino. |
| Flexível | A caixa de seleção Exigir a atualização dos branches antes da mesclagem não está marcada. | O branch não precisa estar atualizado com o branch base antes da mesclagem. | Serão necessárias menos compilações, já que você não precisará atualizar o branch head depois que outros colaboradores fizerem merge de pull requests. As verificações de status poderão falhar depois que você fizer merge do branch, caso haja alterações incompatíveis com o branch base. |
| Desabilitado | A caixa de seleção Exigir a aprovação de verificações de status antes da mesclagem não está marcada. | O branch não tem restrições de merge. | Se as verificações de status obrigatórias não estiverem habilitadas, os colaboradores poderão fazer merge do branch a qualquer momento, estando ou não atualizados com o branch base. Isso aumenta a possibilidade de alterações incompatíveis. |
Para obter informações sobre solução de problemas, confira Solução de problemas de verificações de status necessárias.
Definir proteção contra mesclagem do code scanning
Se seus repositórios estiverem configurados com o code scanning, você poderá usar conjuntos de regras para evitar que pull requests sejam mescladas quando uma das seguintes condições for atendida:
-
Uma ferramenta necessária encontrou um alerta do code scanning de uma gravidade definida em um conjunto de regras.
-
Uma análise de ferramenta necessária do code scanning ainda está em andamento.
-
Uma ferramenta necessária do code scanning não está configurada para o repositório.
Para saber mais, confira Definir proteção contra mesclagem de verificação de código. Para obter informações mais gerais sobre o code scanning, confira Sobre a varredura de código.
Bloquear pushes forçados
Você pode impedir que os usuários forcem o push para os branches ou as tags de destino. Essa regra é habilitada por padrão.
Se alguém forçar pushes para um branch ou uma tag, os commits nos quais outros colaboradores basearam os respectivos trabalhos poderão ser removidos do histórico do branch ou da tag. Isso poderá resultar em conflitos de mesclagem ou em pull requests corrompidas. O push forçado também pode ser usado para excluir branches ou apontar um branch para commits que não foram aprovados em uma solicitação de pull.
A habilitação de pushes forçados não substituirá nenhuma outra regra de proteção de branch. Por exemplo, se um branch exigir um histórico de commit linear, você não poderá forçar commits a mesclar commits para esse branch.
Você não poderá habilitar os pushes forçados em um branch se um administrador do site bloquear os pushes forçados em todos os branches do seu repositório. Para saber mais, confira Aplicar as políticas de gerenciamento do repositório na sua empresa.
Se um administrador do site bloquear pushes forçados apenas para o branch padrão, você ainda poderá habilitar pushes forçados para qualquer outra tag ou outro branch.
Exigir que os fluxos de trabalho passem antes da mesclagem
Os fluxos de trabalho do conjunto de regras podem ser configurados no nível da organização para exigir que os fluxos de trabalho passem antes de mesclar solicitações de pull request. Para obter mais informações, confira "Criar conjuntos de regras para repositórios na sua organização".
Para mais informações sobre como solucionar problemas comuns de definição de configuração de fluxo de trabalho, confira Solução de problemas de regras.
Usando um arquivo de fluxo de trabalho
Para usar essa regra, você deve primeiro criar um arquivo de fluxo de trabalho. O arquivo de fluxo de trabalho precisa estar em um repositório que corresponda à visibilidade dos repositórios nos quais você deseja executá-lo. Especificamente, um fluxo de trabalho público pode ser executado em qualquer repositório na sua organização, um fluxo de trabalho interno só pode ser executado em repositórios internos e privados e um fluxo de trabalho privado só pode ser executado em repositórios privados. Para saber mais, confira Sobre fluxos de trabalho.
Se o arquivo de fluxo de trabalho estiver em um repositório interno ou privado e você quiser usar esse fluxo de trabalho em outros repositórios na organização, será necessário permitir o acesso ao fluxo de trabalho de fora do repositório. Para saber mais, confira Permitir o acesso a componentes em um repositório interno ou Permitir o acesso a componentes em um repositório interno.
Ao adicionar essa regra a um conjunto de regras, nas suas definições de organização, você selecionará o repositório de origem e o fluxo de trabalho que deseja impor.
Usando o modo "Avaliar" para fluxos de trabalho de conjunto de regras
Se um fluxo de trabalho do conjunto de regras for executado no modo "Avaliar" e for aprovado, você poderá definir o fluxo de trabalho do conjunto de regras para o modo "Ativo" e mesclar sua solicitação de pull request sem acionar uma nova execução do fluxo de trabalho.
Se você abrir uma pull request antes de criar o conjunto de regras no modo "Avaliar", ainda poderá mesclar a pull request, já que o conjunto de regras não é imposto.
Para obter mais informações sobre os status de imposição, confira Criar conjuntos de regras para um repositório.
Gatilhos de eventos com suporte
Os fluxos de trabalho do conjunto de regras oferecem suporte usando os eventos pull_request, pull_request_target e merge_group. Como resultado, você deve especificar um ou mais desses eventos na seção on: do fluxo de trabalho para que o fluxo de trabalho seja executado por um conjunto de regras.
Todos os filtros especificados para os eventos com suporte são ignorados - por exemplo, branches, branches-ignore, paths, types e assim por diante. O fluxo de trabalho é acionado apenas e sempre pelos tipos de atividade padrão dos eventos com suporte.
| Evento | Tipos de atividade padrão |
|---|---|
pull_request | opened, synchronize, reopened |
pull_request_target | opened, synchronize, reopened |
merge_group | checks_requested |
Direcionamento de ramificações específicas com seu fluxo de trabalho do conjunto de regras
A aplicação dessa regra bloqueará os envios diretos porque os fluxos de trabalho do conjunto de regras são executados como parte da experiência de solicitação de pull request e fila de mesclagem. Por isso, você não deve aplicar essa regra a um conjunto de regras destinado a todas as ramificações no repositório.
Essa regra só deve ser adicionada a conjuntos de regras que visam ramificações em que todas as alterações na ramificação são executadas por pull request.
Restrições de metadados
Note
Se você fizer uma mesclagem squash para uma ramificação, os commits nessa ramificação devem atender a todos os requisitos de metadados para a ramificação base.
As organizações com um plano do GitHub Enterprise podem acessar regras adicionais para controlar como os metadados de commit precisam ser formatados. Use cadeias de caracteres literais ou uma sintaxe de expressão regular para definir um padrão com o qual os metadados de commit precisam estar em conformidade. Por exemplo, você pode exigir que as mensagens de commit contenham um número de problema do GitHub ou que o autor do commit tenha um endereço de email que termina com @octoorg.com. Você também pode controlar o formato de novos nomes de branches e de tags. Para ver uma seleção de expressões regulares úteis para metadados de commit, confira Criar conjuntos de regras para um repositório.
Se um colaborador tentar atualizar uma tag ou um branch com um commit que não atenda aos seus requisitos, o colaborador verá um erro informando o que havia de errado com o commit. Quando o usuário efetua um push, esse erro pode ser exibido na linha de comando. Contudo, quando o quando o usuário tenta fazer um commit ou mesclar uma solicitação de pull, ele aparece no GitHub.com. Os commits são imutáveis no Git: depois que um colaborador tiver criado um commit, ele não poderá editar os metadados do commit, ou seja, talvez ele precise fazer uma troca de base para reescrever o histórico de commits com novos commits para contribuir com sucesso com o respectivo trabalho para o repositório.
As restrições de metadados são úteis para impor a consistência entre os commits no histórico de um branch. Isso pode ser útil para impor a adesão às melhores práticas, como a especificação Commits Convencionais, ou para integração a ferramentas que dependem de metadados de commit. Por exemplo, é mais fácil executar scripts com base no conteúdo de uma mensagem do commit se todas as mensagens seguem um formato previsível. O ideal é usar restrições de metadados como alternativa para configurar scripts de gancho de pré-recebimento personalizados. Para obter mais informações, confira [AUTOTITLE] (/admin/policies/enforcing-policy-with-pre-receive-hooks/about-pre-receive-hooks).
Considerações importantes sobre as restrições de metadados
As restrições de metadados bloqueiam as "atualizações de referência". Se um colaborador efetuar push de um trabalho que inclua um commit que não atenda aos requisitos, o push não será rejeitado, mas a tag ou o branch ao qual ele é direcionado não será atualizado. Tecnicamente, os commits ainda entram no repositório: os commits serão "recuperáveis" (você poderá navegar até eles no repositório), mas não "acessíveis" (eles não estão conectados ao histórico de uma tag ou de um branch). Se o push do colaborador também incluir um trabalho em outros branches ou outras tags, com os commits que atendam aos requisitos desses branches ou dessas tags, essas referências serão atualizadas com sucesso.
As restrições de metadados podem aumentar o atrito para as pessoas que contribuem para um repositório. Em geral, se você impuser restrições de metadados, deverá fazer isso em um conjunto limitado de branches para evitar afetar o trabalho diário dos colaboradores. Por exemplo, em vez de exigir mensagens de commit consistentes em qualquer branch do tópico no qual um colaborador possa trabalhar, você deve exigir somente mensagens de commit consistentes em main e, em seguida, exigir pull requests em main.
Se você usar mesclagens squash, lembre que as restrições de metadados são avaliadas antes da mesclagem, portanto, todos os commits na solicitação de pull devem atender aos requisitos. Para restrições de metadados que se aplicam a e-mails de confirmação, o padrão também deve incluir noreply@github.com para mesclagens squash para satisfazer a restrição.
Quando você adiciona restrições de metadados a uma tag ou a um branch existente, as regras são impostas para novos commits enviados por push para a tag ou o branch desse ponto em diante, mas não são impostas em relação ao histórico existente da tag ou do branch.