Sobre branches protegidos

Sobre as regras de proteção do branch

É possível aplicar certos fluxos de trabalho ou requisitos antes que um colaborador possa fazer push de alterações em um branch no repositório, incluindo o merge de um pull request no branch, criando uma regra de proteção de branch. Os atores só podem ser adicionados a listas de bypass quando o repositório pertence a uma organização.

Por padrão, cada regra de proteção de branch desabilita push forçado para os branches correspondentes e impede que os branches correspondentes sejam excluídos. Você pode, opcionalmente, desabilitar essas restrições e habilitar configurações adicionais de proteção de branches.

Por padrão, as restrições de uma regra de proteção de branch não se aplicam a pessoas com permissões de administrador para o repositório ou funções personalizadas com a permissão "ignorar proteções de branch". Você pode aplicar opcionalmente as restrições a administradores e funções com a permissão "ignorar proteções de branch" também. Para saber mais, confira Gerenciando as funções de repositórios personalizados para uma organização.

Você pode criar uma regra de proteção de branch em um repositório para um branch específico, para todos os branches ou para qualquer branch que corresponda a um padrão de nome especificado com a sintaxe fnmatch. Por exemplo, para proteger os branches que contêm a palavra release, você pode criar uma regra de branch para *release*. Para obter mais informações sobre padrões de nomes de branches, confira Gerenciar uma regra de proteção de ramo.

Você pode configurar um pull request para fazer merge automaticamente quando todos os requisitos de merge forem atendidos. Para saber mais, confira Mesclar automaticamente uma pull request.

Sobre as configurações de proteção do branch

Para cada regra de proteção do branch, você pode escolher habilitar ou desabilitar as seguintes configurações. * Exigir revisões de solicitação de pull antes da mesclagem * Exigir verificações de status antes do merge * Exigir resolução de discussão antes de realizar o merge * Exigir commits assinados * Exigir histórico linear

•           [Fila de mesclagem obrigatória](#require-merge-queue)
  

•         [Exigir que as implantações sejam concluídas antes da mesclagem](#require-deployments-to-succeed-before-merging)
  

•         [Bloquear branch](#lock-branch)
  

•         [Não permitir que as configurações acima sejam ignoradas](#do-not-allow-bypassing-the-above-settings)
  

•           [Restringir quem pode enviar dados para branches correspondentes](#restrict-who-can-push-to-matching-branches)
  

•         [Permitir pushes forçados](#allow-force-pushes)
  

•         [Permitir exclusões](#allow-deletions)
  

Para obter mais informações sobre como configurar a proteção de branch, confira Gerenciar uma regra de proteção de ramo.

Exigir revisões de pull request antes do merge

Os administradores do repositório ou funções personalizadas com a permissão "edit repository rules" 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 necessárias, os colaboradores só podem fazer push das alterações em um branch protegido por meio de um pull request aprovado pelo número necessário de revisores com permissões de gravação.

Se uma pessoa com permissões de administrador escolher a opção Solicitar alterações em uma revisão, ela precisará aprovar a solicitação de pull antes que a mesclagem possa ser feita. 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.

Se um colaborador tentar fazer merge de um pull request com revisões pendentes ou rejeitadas no branch protegido, o colaborador receberá uma mensagem de erro.

remote: error: GH006: Protected branch update failed for refs/heads/main.
remote: error: Changes have been requested.

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 do diff no ponto em que um pull request é aprovado. 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 base, confira Sobre solicitação de pull.

Opcionalmente, você pode restringir a capacidade de ignorar comentários de pull request para pessoas ou equipes específicas. Para saber mais, confira Ignorar uma revisão de pull request.

Opcionalmente, você pode optar por exigir análises dos proprietários do código. Se você o fizer, qualquer pull request que afeta código com o proprietário do código deverá ser aprovado pelo proprietário desse código antes que o pull request possa ser mesclada no branch protegido.

Opcionalmente, você pode exigir que o push mais recente, passível de revisão, seja aprovado por alguém que não seja a pessoa que fez o push. 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.

Exigir verificações de status antes do merge

As verificações de status necessárias devem ter um status successful, skipped ou neutral para que os colaboradores possam fazer alterações em um branch protegido. As verificações de status necessárias podem ser verificações ou status de commit. 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.

Depois de habilitar as verificações de status obrigatórias, todas elas deverão ser aprovadas para que os colaboradores possam integrar as alterações no branch protegido. Depois que todas as verificações de status necessárias passarem, quaisquer commits devem ser enviados por push para outro branch e, em seguida, mesclados ou enviados por push diretamente para o branch protegido.

Qualquer pessoa ou integração com permissões de escrita em um repositório pode definir o estado de qualquer verificação de status no repositório, mas, em alguns casos, você pode querer aceitar uma verificação de status apenas de um GitHub App específico. Ao adicionar uma verificação de status obrigatória, você pode selecionar um aplicativo que definiu recentemente essa verificação como a fonte esperada de atualizações de status. Se o status for definido por qualquer outra pessoa ou integração, a mesclagem não será permitida. Se selecionar "qualquer fonte", ainda poderá verificar manualmente o autor de cada status, listado na caixa de mesclagem.

Você pode configurar as verificações de status obrigatórias como "flexível" ou "rígida". 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 mesclagem	Considerações

          **Rigoroso** | A caixa de seleção **Exigir que as ramificações estejam atualizadas antes da mesclagem** está selecionada. | O branch **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 mesclar o branch a qualquer momento, independentemente de se está atualizado ou não 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 para checagens de status obrigatórias.

Exigir resolução de conversa antes da mesclagem

Exige que todos os comentários no pull request sejam resolvidos antes de poder fazer merge em um branch protegido. Isso garante que todos os comentários sejam resolvidos ou reconhecidos antes do merge.

Exigir commits assinados

Quando você habilitar a assinatura de commit obrigatória em um branch, os colaboradores e os bots 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.

• Se você habilitou o modo vigilante, que indica que seus commits serão sempre assinados, todos os commits que GitHub identificar como "parcialmente verificado" serão permitidos em branches que exijam commits assinados. Para obter mais informações sobre o modo vigilante, confira Exibindo status de verificação para todos os seus commits.
• 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. Também é possível mesclar commits assinados e verificados na ramificação usando uma solicitação de pull. No entanto, você não pode combinar por squash nem mesclar uma solicitação de pull na ramificação em GitHub, a menos que seja o autor da solicitação de pull . Você pode combinar por squash e mesclar as solicitações de pull localmente. Para saber mais, confira Fazer check-out de pull requests no local.

Para obter mais informações sobre métodos de mesclagem, confira Sobre métodos de mesclagem no GitHub.

Exigir histórico linear

Aplicar o histórico linear de commit impede que os colaboradores façam push de commits de merge no branch. Nesse caso, qualquer pull requests mescladas no branch protegido devem usar um merge squash ou um merge rebase. 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 fusões 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 Configurando a fusão de pull requests.

Exigir uma fila de fusão

Uma fila de mesclagem ajuda a aumentar a velocidade automatizando mesclagens de solicitação de pull em um branch ocupado e garantindo que o branch nunca seja interrompido por alterações incompatíveis.

A fila de mesclagem oferece os mesmos benefícios que a proteção de branch Exigir que os branches sejam atualizados antes da mesclagem, mas não exige que o autor da solicitação de pull atualize o branch de solicitação de pull e aguarde a conclusão das verificações de status para tentar a mesclagem.

O uso de uma fila de mesclagem é útil principalmente em branches que têm um número relativamente alto de solicitações de pull de vários usuários diferentes sendo mescladas todos os dias.

Depois que uma solicitação de pull é aprovada em todas as verificações de proteção de branch necessárias, o usuário com acesso de gravação no repositório pode adicioná-la a uma fila de mesclagem. A fila de mesclagem garante que as alterações da solicitação de pull sejam aprovadas em todas as verificações de status necessárias quando aplicadas à versão mais recente do branch de destino e às solicitações de pull que já estão na fila.

Uma fila de mesclagem pode usar GitHub Actions ou o próprio provedor de CI para executar as verificações necessárias nas solicitações de pull em uma fila de mesclagem. Para saber mais, confira Documentação do GitHub Actions.

O GitHub mescla a pull request de acordo com a estratégia de merge configurada na proteção de branch após a aprovação de todas as verificações de CI obrigatórias. Para obter mais informações sobre filas de mesclagem, confira Como gerenciar uma fila de mesclagem.

Exigir que as implantações tenham êxito antes da mesclagem

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 teste antes que essas sejam mescladas com o branch padrão.

Bloquear ramificação

O bloqueio de um branch vai tornar o branch somente leitura e garantir que nenhum commit seja feito nele. Também não é possível excluir as ramificações bloqueadas.

Por padrão, um repositório bifurcado não permite sincronização com o repositório upstream. Você pode habilitar a opção Permitir a sincronização de fork para efetuar pull de alterações do repositório upstream, impedindo outras contribuições para o branch do fork.

Não permitir que as configurações acima sejam ignoradas

Por padrão, as restrições de uma regra de proteção de branch não se aplicam a pessoas com permissões de administrador para o repositório ou funções personalizadas com a permissão "ignorar proteções de branch" em um repositório.

Você pode habilitar essa configuração para aplicar as restrições a administradores e funções com a permissão "ignorar proteções de branch" também. Para saber mais, confira Gerenciando as funções de repositórios personalizados para uma organização.

Restringir quem pode fazer push para branches correspondentes

Você pode habilitar restrições de ramificação nos repositórios públicos pertencentes a uma organização do GitHub Free e em todos os repositórios pertencentes a uma organização que usa o GitHub Team ou o GitHub Enterprise Cloud.

Ao habilitar as restrições de branches, apenas usuários, equipes ou aplicativos com permissão podem fazer push para o branch protegido. Você pode visualizar e editar usuários, equipes ou aplicativos com acesso de push a um branch protegido nas configurações do branch protegido. Quando as verificações de status forem necessárias, as pessoas, as equipes e os aplicativos com permissão para fazer push em um branch protegido ainda serão impedidos de realizar a mesclagem no branch se a verificação necessária falhar. As pessoas, equipes e aplicativos que têm permissão para fazer push em um branch protegido ainda precisarão criar um pull request quando forem necessários pull requests.

Opcionalmente, você pode aplicar as mesmas restrições à criação de filiais que correspondam à regra. Por exemplo, se você criar uma regra que só permita que uma determinada equipe faça push para quaisquer branches que contenham a palavra release, somente os membros dessa equipe poderão criar um novo branch que contenha a palavra release.

Você só pode fornecer acesso de push a um branch protegido, ou dar permissão para criar um branch correspondente, a usuários, equipes ou GitHub Apps instalados com acesso de gravação a um repositório. As pessoas e os aplicativos com permissões de administrador em um repositório sempre conseguem enviar por push a um branch protegido ou criar um branch correspondente.

Permitir push forçado

Por padrão, GitHub bloqueia pushes forçados em todos os branches protegidos. Ao habilitar push forçado em um branch protegido, você pode escolher um dos dois grupos que podem fazer push forçado:

1. Permitir que todos com, no mínimo, permissões de gravação para que o repositório faça push forçado no branch, incluindo aqueles com permissões de administrador.
2. Permitir apenas pessoas ou equipes específicas façam push forçado no branch.

Se alguém forçar pushes para um branch, o push forçado poderá indicar que commits em que outros colaboradores basearam os respectivos trabalhos serão removidos do histórico do branch. As pessoas podem ter conflitos de merge ou pull requests corrompidos. 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.

Habilitar push forçado não substituirá qualquer outra regra de proteção do 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.

Permitir exclusões

Por padrão, você não pode excluir um branch protegido. Ao habilitar a exclusão de um branch protegido, qualquer pessoa com permissão de gravação no repositório pode excluir o branch.