Skip to main content

Como gerenciar uma fila de mesclagem

É possível aumentar a velocidade de desenvolvimento com uma mesclagem das filas para pull requests no seu repositório.

Who can use this feature?

People with admin permissions can manage merge queues for pull requests targeting selected branches of a repository.

As filas de mesclagem de solicitação de pull estão disponíveis em qualquer repositório público pertencente a uma organização ou em repositórios privados pertencentes a organizações que usam GitHub Enterprise Cloud. Para mais informações, confira "Planos do GitHub".

Sobre as filas de mesclagem

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 obter mais informações, confira "Documentação do GitHub Actions".

Para obter mais informações de como mesclar uma solicitação de pull usando uma fila de mesclagem, confira "Como mesclar uma solicitação de pull com uma fila de mesclagem".

Configurar fluxos de trabalho de CI (integração contínua) para filas de mesclagem

Observações:

  • Uma fila de mesclagem não pode ser habilitada com regras de proteção de branch que usam caracteres curinga (*) no padrão de nome do branch.
  • Uma fila de mesclagem aguardará até que as verificações necessárias sejam relatadas antes de prosseguir com a mesclagem. É necessário atualizar sua configuração de CI a fim de disparar e relatar eventos do grupo de mesclagem ao exigir uma fila de mesclagem.

Disparando verificações de grupo de mesclagem com GitHub Actions

Você precisa usar o evento merge_group para disparar GitHub Actions quando uma solicitação de pull é adicionada a uma fila de mesclagem.

Observação: se o repositório usa GitHub Actions para executar as verificações necessárias nas solicitações de pull no repositório, atualize os fluxos de trabalho para incluir o evento merge_group como um gatilho adicional. Caso contrário, as verificações de status não serão disparadas quando você adicionar uma solicitação de pull a uma fila de mesclagem. A mesclagem falhará, pois o verificação de status obrigatória não será relatada. O evento merge_group é separado dos eventos pull_request e push.

Um fluxo de trabalho que relata uma verificação exigida pelas proteções do branch de destino seria semelhante a este:

on:
  pull_request:
  merge_group:

Para saber mais sobre o evento merge_group, confira "Eventos que disparam fluxos de trabalho".

Disparar verificações de grupo de mesclagem com provedores de CI terceiros

Com provedores de CI terceiros, poderá ser necessário atualizar a configuração de CI para ser executada quando um branch que começa com o prefixo especial gh-readonly-queue/{base_branch} for criado. Esses são os branches temporários que são criados em seu nome por uma fila de mesclagem e contêm um sha diferente da solicitação de pull.

Como gerenciar uma fila de mesclagem

Os administradores do repositório podem exigir uma fila de mesclagem habilitando a configuração de proteção de branch "Exigir fila de mesclagem" nas regras de proteção do branch base. Para obter mais informações, confira "Gerenciar uma regra de proteção de branch".

Depois de habilitar a configuração "Exigir fila de mesclagem", você também poderá acessar as seguintes configurações:

  • Método de mesclagem: selecione qual método usar ao mesclar solicitações de pull enfileiradas: mesclagem, troca de base ou squash.

  • Simultaneidade de build: o número máximo de webhooks merge_group a serem expedidos (entre 1 e 100), limitando a quantidade total de builds de CI simultâneos. Isso afeta a velocidade das mesclagens que uma fila de mesclagem pode realizar.

  • Mesclar apenas solicitações de pull sem falha: essa configuração determina como a fila de mesclagem forma grupos de solicitações de pull a serem mescladas.

    Habilitado?Descrição
    SimTodas as solicitações de pull precisam atender às verificações necessárias para serem mescladas.
    NãoAs solicitações de pull que falharem nas verificações necessárias poderão ser adicionadas a um grupo, desde que a última solicitação de pull no grupo tenha sido aprovada. Se a última solicitação de pull no grupo foi aprovada nas verificações necessárias, isso significa que as verificações foram aprovadas para o conjunto combinado de alterações no grupo de mesclagem. Deixar essa caixa de seleção desmarcada poderá ser útil se você tiver falhas intermitentes de teste, mas não quiser que falsos negativos segurem a fila.
  • Tempo limite de verificação de status: escolha por quanto tempo a fila deve aguardar uma resposta da CI antes de assumir que as verificações falharam.

  • Limites de mesclagem: selecione o número mínimo e máximo de solicitações de pull a serem mescladas em apenas um grupo (entre 1 e 100) e um tempo limite após o qual a fila deve parar de esperar mais entradas e mesclar com um número de solicitações de pull inferior ao mínimo. O número exato de PRs incluídas em um grupo depende das configurações de uma fila de mesclagem:

    Limite de mesclagemCaso de uso
    Máximo de solicitações de pull a serem mescladasVocê pode especificar o tamanho máximo do grupo. Quando as mesclagens no branch base disparam uma implantação, essa opção é útil para garantir que não sejam implantadas muitas alterações ao mesmo tempo.
    Mínimo de solicitações de pull a serem mescladasVocê pode especificar o tamanho mínimo do grupo. Quando a mesclagem ao branch base dispara um processo longo de build ou implantação de CI, essa opção é útil para não atrasar as próximas entradas na fila.
    Tempo de esperaVocê pode especificar um tempo limite para atingir o tamanho mínimo do grupo, o que permite que grupos menores sejam mesclados quando não houver mais PRs enfileiradas no limite de tempo especificado.

Como funcionam as filas de mesclagem

À medida que as solicitações de pull são adicionadas à fila de mesclagem, a fila de mesclagem garante que elas sejam mescladas na ordem primeiro a entrar, primeiro a sair, em que as verificações necessárias são sempre atendidas.

A fila de mesclagem cria branches temporários com um prefixo especial para validar as alterações da solicitação de pull. Quando uma solicitação de pull é adicionada à fila de mesclagem, as alterações na solicitação de pull são agrupadas em um merge_group com a versão mais recente do base_branch e as alterações de solicitações de pull que já estão na fila. O GitHub mesclará todas essas alterações no base_branch depois que as verificações exigidas pelas proteções do base_branch forem aprovadas.

Para obter mais informações sobre os métodos de mesclagem, confira "Sobre merges de pull request".

CI bem-sucedida

Quando várias solicitações de pull são adicionadas à fila de mesclagem e quando os branches temporários do merge_group têm resultados de CI bem-sucedidos, todas são mescladas. No cenário a seguir, duas solicitações de pull são adicionadas com êxito à fila e mescladas ao branch de destino.

  1. O usuário adiciona a solicitação de pull nº 1 à fila de mesclagem.
  2. A fila de mesclagem cria um branch temporário com o prefixo main/pr-1 que contém alterações de código do branch de destino e da solicitação de pull nº 1. Um evento de webhook do merge_group do tipo checks_requested é expedido e a fila de mesclagem aguarda uma resposta do provedor de CI.
  3. O usuário adiciona a solicitação de pull nº 2 à fila de mesclagem.
  4. A fila de mesclagem cria um branch temporário com o prefixo main/pr-2 que contém alterações de código do branch de destino, da solicitação de pull nº 1 e da solicitação de pull nº 2 e envia webhooks.
  5. Quando a API do GitHub receber respostas de CI bem-sucedidas dos branches main/pr-1 e main/pr-2 do merge_group, o branch main/pr-2 temporário será mesclado no branch de destino. O branch de destino agora contém as duas alterações da solicitação de pull nº 1 e nº 2.

CI com falha

Após o agrupamento de uma solicitação de pull com a última versão do branch de destino e as alterações que já estão na fila, se houver verificações de status obrigatórias com falha ou conflitos com o branch base, a solicitação de pull será removida da fila. A linha do tempo da solicitação de pull exibirá o motivo pelo qual ela foi removida da fila.

O cenário a seguir descreve o que acontece quando uma CI relata um status de falha de uma solicitação de pull.

  1. O usuário adiciona a solicitação de pull nº 1 à fila de mesclagem.
  2. A fila de mesclagem cria um branch temporário com o prefixo main/pr-1 que contém alterações de código do branch de destino e da solicitação de pull nº 1. Um evento de webhook do merge_group do tipo checks_requested é expedido e a fila de mesclagem aguarda uma resposta do provedor de CI.
  3. O usuário adiciona a solicitação de pull nº 2 à fila de mesclagem.
  4. A fila de mesclagem cria um branch temporário com o prefixo main/pr-2 que contém alterações de código do branch de destino, da solicitação de pull nº 1 e da solicitação de pull nº 2 e envia webhooks.
  5. Quando a API do GitHub recebe um status de falha de main/pr-1, a fila de mesclagem remove automaticamente a solicitação de pull nº 1.
  6. A fila de mesclagem recria o branch temporário com o prefixo main/pr-2 para conter apenas as alterações do branch de destino e da solicitação de pull nº 2.
  7. Quando a API do GitHub receber respostas de CI bem-sucedidas do branch main/pr-2 do merge_group, o branch main/pr-2 temporário será mesclado no branch de destino sem a solicitação de pull nº 1 incluída.

Há vários motivos pelos quais uma solicitação de pull pode ser removida de uma fila de mesclagem:

  • O serviço de CI configurado está relatando falhas de teste de um grupo de mesclagem
  • Tempo limite atingido aguardando um resultado de CI bem-sucedido com base na configuração de tempo limite definida
  • Usuário solicitando uma remoção por meio da API ou interface da fila de mesclagem
  • Falha de proteção de branch que não pôde ser resolvida automaticamente

Saltar para o topo da fila

Ao adicionar uma solicitação de pull a uma fila de mesclagem, há uma opção para colocá-la no topo da fila.

Observação: o salto para o topo da fila de mesclagem gera uma recompilação completa de todas as solicitações de pull em andamento, pois a reordenação da fila causa uma interrupção no grafo de commit. A utilização intensa desse recurso pode reduzir a velocidade das mesclagens para o branch de destino.

O cenário a seguir descreve o que acontece quando um usuário faz um salto na fila.

  1. O usuário adiciona a solicitação de pull nº 1 à fila de mesclagem.
  2. A fila de mesclagem cria um branch temporário com o prefixo main/pr-1 que contém alterações de código do branch de destino e da solicitação de pull nº 1. Um evento de webhook do merge_group do tipo checks_requested é expedido e a fila de mesclagem aguarda uma resposta do provedor de CI.
  3. O usuário adiciona a solicitação de pull nº 2 à fila de mesclagem.
  4. A fila de mesclagem cria um branch temporário com o prefixo main/pr-2 que contém alterações de código do branch de destino, da solicitação de pull nº 1 e da solicitação de pull nº 2 e envia webhooks.
  5. O usuário adiciona a solicitação de pull nº 3 à fila de mesclagem com a opção de salto que introduz uma interrupção no grafo de commit.
  6. A fila de mesclagem cria um branch temporário com o prefixo main/pr-3 que contém alterações de código do branch de destino e da solicitação de pull nº 3 e expede webhooks.
  7. A fila de mesclagem recria os branches temporários com o prefixo main/pr-1 e main/pr-2 que contêm as alterações da solicitação de pull nº 3 e expede webhooks.

Leitura adicional