Skip to main content

Sobre branches protegidos

Você pode proteger branches importantes definindo regras de proteção de branch, que definem se os colaboradores podem excluir ou forçar push para o branch e definem os requisitos para todos os pushes para o branch, tais como verificações de status de passagem ou um histórico linear de commits.

Branches protegidos estão disponíveis em repositórios públicos com GitHub Free e GitHub Free para organizações e em repositórios públicos e privados com GitHub Pro, GitHub Team, GitHub Enterprise Cloud e GitHub Enterprise Server. Para obter mais informações, consulte os "produtos do GitHub".

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.

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. Opcionalmente, você também pode escolher incluir administradores.

Você pode criar uma regra de proteção de branch em um repositório para um branch específico, todos os branches, ou qualquer branch que corresponde a um padrão de nome que você especificar com a sintaxe fnmatch. Por exemplo, para proteger qualquer branch que contenha a palavra versão, você pode criar uma regra de branch para *versão*. Para obter mais informações sobre os padrões de nomes do branch, consulte "Gerenciar uma regra de proteção de branch".

Você pode configurar um pull request para fazer merge automaticamente quando todos os requisitos de merge forem atendidos. Para obter mais informações, consulte "Fazer merge automático de um 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.

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

Exigir revisões de pull request antes do merge

Os administradores do repositório podem exigir que todos os pull requests recebam um número específico de revisões antes que alguém faça o merge do pull request 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, essa pessoa deverá aprovar o pull request antes que o merge possa ser efetuado. 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.

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 escolher ignorar as aprovações de pull request obsoletas quando commits são enviados por push. Se alguém fizer push de um commit que modifica código para um pull request aprovado, a aprovação será ignorada e o pull request não poderá ser mesclado. Isso não se aplica se o colaborador fizer push de commits que não modificam código, como mesclar o branch de base no branch do pull request. Para obter mais informações sobre branch base, consulte "Sobre pull requests".

Opcionalmente, você pode restringir a capacidade de ignorar comentários de pull request para pessoas ou equipes específicas. Para obter mais informações, consulte "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.

Exigir verificações de status antes do merge

As verificações de status obrigatórias garantem que todos os testes de CI sejam aprovados antes que os colaboradores possam fazer alterações em um branch protegido. Para obter mais informações, consulte "Configurar branches protegidos" e "Habilitar verificações de status obrigatórias". Para obter mais informações, consulte "Sobre verificações de status".

Antes de habilitar as verificações de status necessárias, é necessário configurar o repositório para usar a API de status. Para obter mais informações, consulte "Repositórios" na documentação do REST.

Depois de habilitar a verificação de status obrigatória, todas as verificações de status necessárias deverão passar para que os colaboradores possam fazer merge das 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 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 aplicativo GitHub específico. Ao adicionar a verificação de status necessária, você pode selecionar um aplicativo que definiu essa verificação recentemente como a fonte esperada de atualizações de status. Se o status for definido por qualquer outra pessoa ou integração, o merge não será permitido. Se você selecionar "qualquer fonte", você ainda pode verificar manualmente o autor de cada status, listado na caixa de merge.

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óriaConfiguraçãoRequisitos de mergeConsiderações
RígidaA caixa de seleção Exigir a atualização dos branches antes de fazer merge fica marcada.O branch precisa ser atualizado no branch base antes do merge.Este é o comportamento padrão para verificações de status obrigatórias. Podem ser necessárias mais compilações, já que você precisará atualizar o branch head depois que outros colaboradores fizerem merge de pull requests no branch base protegido.
FlexívelA caixa de seleção Exigir a atualização dos branches antes de fazer merge não fica marcada.O branch não precisa ser atualizado no branch base antes do merge.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.
DesabilitadaA caixa de seleção Require status checks to pass before merging (Exigir verificações de status para aprovação antes de fazer merge) não fica 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 a solução de problemas, consulte "Solucionar problemas para as verificações de status obrigatórias".

Exigir resolução de conversa antes de merge

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

Ao habilitar a assinatura de commit obrigatória em um branch, os contribuidores e bots só podem fazer push de commits que foram assinados e verificados no branch. Para obter mais informações, consulte "Sobre verificação de assinatura commit".

Notas:

  • Se você habilitou o modo vigilante, que indica que seus commits serão sempre assinados, todos os commits que GitHub indentificar como "parcialmente verificado" serão permitidos em branches que exijam commits assinados. Para obter mais informações sobre o modo vigilante, consulte "Exibir 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. Você também pode mesclar commits assinados e verificados no branch usando uma pull request no GitHub. No entanto, você não pode combinar por squash e fazer o merge de uma pull request no branch em GitHub, a menos que você seja o autor da pull request. Você pode combinar por squash e merge pull requests localmente. Para obter mais informações, consulte "Fazer checkout de pull requests localmente".

Para obter mais informações sobre métodos de merge, consulte "Sobre métodos de merge em 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. Isto significa que quaisquer pull requests mesclada 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 merge, consulte "Sobre merges de pull requests".

Antes de exigir um histórico de commit linear, seu repositório deve permitir merge squash ou merge rebase. Para obter mais informações, consulte "Configurando merges da pull request".

Exigir uma fila de fusão

Note: The pull request merge queue feature is currently in limited public beta and subject to change. Organizations owners can request early access to the beta by joining the waitlist.

Merge queues for pull requests can increase the rate at which pull requests are merged into a busy default branch, whilst ensuring that CI checks pass.

Merge queues use GitHub Actions. For more information about actions, see "GitHub Actions."

Once a pull request has passed any required checks and approvals, a contributor with write access can add the pull request to the merge queue. The queue then creates a temporary branch with that pull request and any pull requests ahead of it in the queue, and triggers any required continuous integration (CI) checks.

Once CI checks pass, GitHub merges the pull request by fast-forwarding the default branch. The merge queue will use merge commits if the "Require linear history" branch protection setting is turned off, and the "Rebase and merge" method otherwise.

For more information about merge queues, see "Using a merge queue."

Incluir administradores

Por padrão, as regras de branch protegidos não se aplicam a pessoas com permissões de administrador em um repositório. Você pode habilitar essa configuração para incluir administradores em suas regras de branch protegido.

Restringir quem pode fazer push para branches correspondentes

Você pode habilitar as restrições do branch se seu repositório for propriedade de uma organização que usa GitHub Team ou 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 são necessárias, as pessoas, equipes, e aplicativos que têm permissão para fazer push em um branch protegido ainda serão impedidos de realizar o merge 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.

Você só pode dar acesso de push a um branch protegido a usuários, equipes ou Aplicativos do GitHub 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 fazer push em um branch protegido.

Permitir push forçado

Por padrão, os blocks do GitHub fazem push forçado 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 fizer um push forçado em um branch, ele poderá substituir commits em que outros colaboradores colaboradores basearam seu trabalho. As pessoas podem ter conflitos de merge ou pull requests corrompidos.

Habilitar push forçado não irá substituir quaisquer outras regras 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.

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.