Como gerenciar uma fila de mesclagem

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

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.

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
  Sim	Todas as solicitações de pull precisam atender às verificações necessárias para serem mescladas.
  Não	As 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, 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 um branch base (entre 1 e 100) e um tempo limite após o qual a fila deve parar de esperar mais entradas e fazer a mesclagem com um número de solicitações de pull inferior ao mínimo.

Limite de mesclagem	Caso de uso
Máximo de solicitações de pull a serem mescladas	Você 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 mescladas	Você 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 espera	Você 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.

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

• "Como mesclar uma solicitação de pull com uma fila de mesclagem"
• "Sobre branches protegidos"