管理合并队列

您可以使用代码库中拉取请求的合并队列来提高开发速度。

谁可以使用此功能？

具有管理员权限的人员可以管理针对代码库选定分支的拉取请求的合并队列。

拉取请求合并队列可用于组织拥有的任何公共代码库，或使用 GitHub Enterprise Cloud 的组织拥有的私有代码库。有关更多信息，请参阅“GitHub 的计划”。

本文内容

关于合并队列

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

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

在每天从许多不同用户合并大量拉取请求的分支上，使用合并队列尤其有用。

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

合并队列可以使用 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与拉取请求不同。

管理合并队列

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

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

  • 合并方法：选择合并排队拉取请求时要使用的方法：合并、变基或压缩。

  • 构建并发性：要分派的merge_groupwebhook 的最大数量（介于1和100之间），从而限制并发 CI 构建的总数。这会影响合并队列可以完成的合并速度。

  • 仅合并非失败的拉取请求：此设置决定合并队列如何形成要合并的拉取请求组。

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

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

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

    注意

    合并限制不会组合merge_group**构建**。合并限制仅在一次或多个merge_group满足构建检查后才影响到基分支的合并。

    合并限制用例
    要合并的最大拉取请求数您可以指定最大组大小，这在合并到基分支会触发部署并且您希望确保不会一次部署太多更改时非常有用。
    要合并的最小拉取请求数您可以指定最小组大小，这在合并到基分支会触发冗长的 CI 构建或部署过程并且您不想阻止队列中的后续条目时非常有用。
    等待时间您可以指定达到最小组大小的超时时间，如果在您指定的时限内没有更多 PR 排队，则允许合并较小的组。

合并队列的工作原理

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

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

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

成功的 CI

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

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

CI 失败

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

以下场景概述了当 CI 报告某个拉取请求的失败状态时会发生的情况。

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

拉取请求可能从合并队列中删除的原因有很多。

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

跳到队列顶部

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

注意

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

以下场景概述了用户跳过队列时会发生的情况。

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

进一步阅读