管理合并队列

关于合并队列

合并队列通过将拉取请求合并到繁忙分支并确保分支不会因不兼容的更改而中断，从而帮助提高速度。

合并队列提供与要求分支在合并前保持最新分支保护相同的好处，但不需要拉取请求作者更新其拉取请求分支并等待状态检查完成，然后才能尝试合并。

在每天有大量不同用户合并拉取请求的分支上使用合并队列特别有用。

一旦拉取请求通过所有必需的分支保护检查，具有对存储库的写访问权限的用户就可以将拉取请求添加到队列中。合并队列将确保拉取请求的更改在应用到目标分支的最新版本和队列中已有的任何拉取请求时通过所有必需的状态检查。

合并队列可以使用 GitHub Actions 或您自己的 CI 提供商对合并队列中的拉取请求运行必需的检查。有关更多信息，请参阅“GitHub Actions 文档”。

有关使用合并队列合并拉取请求的更多信息，请参阅“使用合并队列合并拉取请求”。

为合并队列配置持续集成 (CI) 工作流

备注

如果分支名称模式中使用了通配符字符 (*)，则无法启用合并队列和分支保护规则。
合并队列将等待必需的检查报告，然后才能继续合并。需要合并队列时，必须更新 CI 配置以触发合并组事件并报告该事件。
合并队列和拉取请求检查是耦合的，并且在分支保护规则或规则集中进行配置。有关详细信息，请参阅“管理合并队列”。

使用 GitHub Actions 触发合并组检查

当拉取请求添加到合并队列时，必须使用 merge_group 事件触发 GitHub Actions 工作流。

注意：如果你的存储库使用 GitHub Actions 对存储库中的拉取请求执行必需的检查，则需要更新工作流以将 merge_group 事件作为附加触发器。否则，当你将拉取请求添加到合并队列时，不会触发状态检查。合并将失败，因为不会报告必需的状态检查。merge_group 事件与 pull_request 和 push 事件是分开的。

报告目标分支的保护所需的检查的工作流如下所示

on:
  pull_request:
  merge_group:

有关 merge_group 事件的详细信息，请参阅“触发工作流的事件”。

使用第三方 CI 提供程序触发合并组检查

对于第三方 CI 提供程序，需要更新 CI 配置，以便在将以特殊前缀 gh-readonly-queue/{base_branch} 开头的分支推送到时运行。这些是合并队列代表你创建的临时分支，并且包含与拉取请求不同的 sha。

代码库管理员可以通过在基本分支的保护规则中启用分支保护设置“要求合并队列”来要求合并队列。有关更多信息，请参阅“管理分支保护规则”。

启用“要求合并队列”设置后，还可以访问以下设置

合并方法：选择在合并排队的 pull 请求时使用哪种方法：合并、变基或压扁。
构建并发：要分派的最大 merge_group webhook 数量（介于 1 和 100 之间），从而限制并发 CI 构建的总量。这会影响合并队列可以完成的合并速度。

仅合并未失败的 pull 请求：此设置决定合并队列如何形成要合并的 pull 请求组。

已启用？	说明
是	所有 pull 请求都必须满足必需的检查才能合并。
否	只要组中的最后一个 pull 请求通过了必需的检查，就可以将失败必需检查的 pull 请求添加到组中。如果组中的最后一个 pull 请求通过了必需的检查，则表示合并组中的一组更改已通过检查。如果您遇到间歇性测试失败，但不想让误报阻碍队列，则可以取消选中此复选框。

状态检查超时：选择队列在假定检查失败之前应该等待 CI 响应多长时间。

合并限制：选择同时合并到基本分支的 pull 请求的最小和最大数量（介于 1 和 100 之间），以及队列停止等待更多条目并在少于最小数量的情况下合并的超时时间。

注意：合并限制不会合并 merge_group 构建。合并限制仅在一次或多次 merge_group 满足构建检查后才影响与基本分支的合并。

合并限制	用例
要合并的最大 pull 请求数	您可以指定最大组大小，这在将与基本分支的合并触发部署时很有用，并且您希望确保不会一次部署太多更改。
要合并的最小 pull 请求数	你可以指定最小组大小，这在合并到你的基本分支触发冗长的 CI 构建或部署流程时很有用，并且你不想在队列中保留以下条目。
等待时间	你可以为达到最小组大小指定超时，这允许较小的组合并，如果在你的指定时间限制内没有更多排队的 PR。

合并队列的工作原理

当将拉取请求添加到合并队列时，合并队列将确保按照先进先出顺序合并它们，其中始终满足所需的检查。

合并队列创建具有特殊前缀的临时分支来验证拉取请求更改。当将拉取请求添加到合并队列时，拉取请求中的更改将分组到一个 merge_group 中，其中包含 base_branch 的最新版本以及队列中排在其前面的拉取请求的更改。一旦 base_branch 的分支保护所需的检查通过，GitHub 将把所有这些更改合并到 base_branch 中。

有关合并方法的信息，请参阅“关于拉取请求合并”。

成功的 CI

当将多个拉取请求添加到合并队列并且临时 merge_group 分支具有成功的 CI 结果时，它们都会被合并。在以下场景中，两个拉取请求已成功添加到队列并合并到目标分支。

用户将拉取请求 #1 添加到合并队列。
合并队列创建一个前缀为 main/pr-1 的临时分支，其中包含来自目标分支和拉取请求 #1 的代码更改。将分发类型为 checks_requested 的 merge_group Webhook 事件，并且合并队列将等待来自你的 CI 提供程序的响应。
用户将拉取请求 #2 添加到合并队列。
合并队列创建一个前缀为 main/pr-2 的临时分支，其中包含来自目标分支、拉取请求 #1 和拉取请求 #2 的代码更改，并分发 Webhook。
当 GitHub API 为 merge_group 分支 main/pr-1 和 main/pr-2 接收成功的 CI 响应时，临时分支 main/pr-2 将合并到目标分支中。目标分支现在包含来自拉取请求 #1 和 #2 的更改。

失败的 CI

在将一个拉取请求与目标分支的最新版本以及队列中领先于它的更改分组后，如果存在失败的必需状态检查或与基本分支的冲突，则该拉取请求将从队列中移除。拉取请求时间线将显示从队列中移除拉取请求的原因。

以下场景概述了当 CI 报告关于一个拉取请求的失败状态时会发生什么。

用户将拉取请求 #1 添加到合并队列。
合并队列创建一个前缀为 main/pr-1 的临时分支，其中包含来自目标分支和拉取请求 #1 的代码更改。将分发类型为 checks_requested 的 merge_group Webhook 事件，并且合并队列将等待来自你的 CI 提供程序的响应。
用户将拉取请求 #2 添加到合并队列。
合并队列创建一个前缀为 main/pr-2 的临时分支，其中包含来自目标分支、拉取请求 #1 和拉取请求 #2 的代码更改，并分发 Webhook。
当 GitHub API 收到 main/pr-1 的失败状态时，合并队列会自动从合并队列中移除拉取请求 #1。
合并队列使用前缀 main/pr-2 重新创建临时分支，以仅包含来自目标分支和拉取请求 #2 的更改。
当 GitHub API 收到 merge_group 分支 main/pr-2 的成功 CI 响应时，临时分支 main/pr-2 将被合并到目标分支中，而不包括拉取请求 #1。

拉取请求可以从合并队列中移除的原因有很多

配置的 CI 服务正在报告合并组的测试失败
根据配置的超时设置，等待成功的 CI 结果超时
用户通过 API 或合并队列界面请求移除
无法自动解决的分支保护失败

跳到队列顶部

将拉取请求添加到合并队列时，可以选择将拉取请求移动到队列顶部。

注意：请注意，跳到合并队列的顶部将导致所有正在进行的拉取请求完全重新构建，因为重新排序队列会在提交图中引入中断。大量使用此功能会降低目标分支的合并速度。

以下场景概述了当用户跳过队列时会发生什么。

用户将拉取请求 #1 添加到合并队列。
合并队列创建一个前缀为 main/pr-1 的临时分支，其中包含来自目标分支和拉取请求 #1 的代码更改。将分发类型为 checks_requested 的 merge_group Webhook 事件，并且合并队列将等待来自你的 CI 提供程序的响应。
用户将拉取请求 #2 添加到合并队列。
合并队列创建一个前缀为 main/pr-2 的临时分支，其中包含来自目标分支、拉取请求 #1 和拉取请求 #2 的代码更改，并分发 Webhook。
用户使用跳过选项将拉取请求 #3 添加到合并队列，这会在提交图中引入中断。
合并队列使用前缀 main/pr-3 创建一个临时分支，其中包含来自目标分支和拉取请求 #3 的代码更改，并分派 Webhook。
合并队列使用前缀 main/pr-1 和 main/pr-2 重新创建临时分支，其中包含来自拉取请求 #3 的更改，并分派 Webhook。

管理合并队列

谁可以使用此功能？

本文内容

关于合并队列

为合并队列配置持续集成 (CI) 工作流

使用 GitHub Actions 触发合并组检查

使用第三方 CI 提供程序触发合并组检查