合并队列让团队可以在一处安排 PR、保持默认分支可用，并合入分支栈，无需每位作者时刻关注变基。
如果团队使用分支栈，队列能够识别分支栈 PR，并将其作为整体处理，而不会把每个 PR 视为互不相关的分支。
功能说明¶
合并队列适用于具备以下一种或多种情况的仓库：
- CI 耗时较长
- 持续有 PR 合入
main或trunk - 经常需要变基，或默认分支推送后导致构建失败
- 需要按顺序合入的分支栈 PR
PR 不会直接合并到默认分支，而是进入队列等待轮到自己。队列决定下一步运行什么、哪些内容需要 CI，以及哪些内容可以安全合并。
要求¶
启用前，请确认满足以下条件：
- 团队版或企业版方案
- 已为代码仓库安装 Cursor GitHub App
- 代码仓库已配置为允许 App 推送或绕过相应的合并限制
- 使用代码仓库的默认分支作为目标分支
以下几项重要限制需要提前说明：
- 目前每个代码仓库仅支持一个合并队列
- 合并队列仅支持代码仓库的默认分支
- 合并队列与 GitHub 合并队列相互独立
如果您的团队已在使用 GitHub 合并队列或其他第三方队列，请使用外部合并队列集成，不要将两个系统作为同一个队列同时运行。
设置合并队列¶
打开 合并队列设置，然后选择要配置的代码仓库。你可以选择以下两种方案：
- 合并队列：完整的分支栈感知队列，推荐大多数团队使用
- 外部合并队列集成：在现有的 GitHub Merge Queue 或其他基于标签的队列之上使用
合并队列的主要设置包括：
- 合并策略：
Squash and merge、Rebase and merge或Merge - 超时：PR 位于队列头部多久后会超时
- 合并队列标签：团队可用于将 PR 加入队列的标签
- 快速前进合并：启用更快的 CI 和分支栈感知队列行为的开关
- CI 设置：CI 的运行位置以及所需的并行度
该应用强烈建议团队使用 Squash and merge，并将普通的 Merge 标记为不推荐。
如果你的代码仓库使用分支保护规则或规则集，请确保 App 具有相应权限。队列不必是唯一允许向默认分支推送的主体也能正常工作，但如果有人绕过队列直接合并，体验会迅速变差。
将 PR 加入队列¶
最常见的入队方式是在 PR 页面操作。为代码仓库启用合并队列后，合并流程会从“立即合并”变为“加入队列”。
如果 PR 属于某个分支栈，队列弹窗可以将所有下层的开放 PR 一并加入队列，而不只是当前查看的那个。这一点很重要：它能让整个分支栈同步推进，无需你手动逐层合并。
你也可以通过标签将 PR 加入队列：
- 应用 合并队列标签，即可将 PR 加入队列
- 如果你的仓库启用了此功能，应用 快速通道标签，可让 PR 排在非快速通道工作之前
有些代码仓库还提供 准备就绪后合并 开关，可在 PR 满足要求后自动合并。
使用合并队列页面¶
主队列视图是 合并队列 页面，分为三个标签页：
- 已排队 显示等待中的项目、正在处理的项目，以及最接近主干的项目
- 活动 显示合并、失败、移除、超时及其他队列事件
- 提交 显示最近合入默认分支的提交
你最常使用的是 已排队 标签页。它会显示：
- PR 或分支栈在队列中的位置
- 队列是否已暂停
- PR 是否已快速通道处理
- 工作是否正在变基、运行 CI、合并或进行失败处理
在页面选项菜单中，你可以：
- 暂停队列
- 恢复队列
- 打开 合并队列设置
暂停队列会阻止合并操作合入，但不会阻止他人将新的 PR 添加到队列。它们会一直等待，直到队列恢复。
了解 PR 的状态¶
当 PR 进入队列后，PR 页面会显示合并队列横幅，作者无需频繁切换标签页即可了解当前进展。
根据状态，横幅可能会告知你：
- PR 正在加入队列
- PR 位于队首
- PR 即将轮到
- CI 正在临时草稿 PR 中运行
- PR 已通过合并队列合并
- PR 因冲突、阻塞因素、超时、提交未签名或其他失败原因被移除
出现问题时，横幅通常会引导你前往下一处有用的位置：
- 返回合并队列
- 前往用于运行 CI 的临时草稿 PR
- 前往失败详情链接
- 如果仓库要求提交签名，前往提交签名设置
快速通道、移除与恢复¶
如果代码仓库启用了此功能，单个 PR 可以以快速通道方式加入队列。快速通道 PR 会跳过非快速通道任务，优先得到处理。
你也可以从队列中移除任务。如果某个 PR 已在处理中，移除它可能会将整个分支栈移出队列，并可能需要稍后重新运行 CI。实际上，“移除”很容易点击，但并不总是没有代价。
如果队列因冲突或阻塞因素移除了某个 PR，通常只需：
- 对 PR 进行变基或重新整理
- 修复导致失败的问题
- 再次将其加入队列
CI 设置与优化¶
启用 快速前进合并 后，您可以选择 CI 的运行方式：
- 在每个 PR 上运行：分支栈中的每个 PR 都需在合并前通过 CI
- 在每个分支栈的最顶层 PR 上运行：每个分支栈都需在合并前通过 CI
- 在一组分支栈的最顶层 PR 上运行：将多个分支栈合并成批次处理
根据代码仓库的配置，您还可以设置：
- 并行并发数
- 批处理等待时间
- 失败处理
- 二分模式
- 最大失败处理次数
失败处理在批处理模式中特别有用。当分组 CI 运行失败时，它可以识别导致失败的分支栈，将安全的分支栈重新入队，并让队列继续推进。
二分模式是该流程中速度较慢但成本更低的版本。它需要更少的 CI 运行次数，对于成本高昂的流水线而言尤为重要。
临时草稿 PR¶
如果启用更激进的 CI 优化，系统可能会创建临时草稿 PR，以便在分组或推测性的队列状态下运行 CI。
这会带来两个面向用户的影响：
- CI 运行期间，PR 横幅可能会链接到临时草稿 PR
- 合并队列成功运行后，原始 PR 在 GitHub 中可能显示为 已关闭 而非 已合并，尽管产品会将其视为已合并
外部合并队列集成¶
如果您的团队已在使用其他合并队列，其使用体验会与 Cursor Review 有所不同。
外部集成支持两种方式：
- GitHub 合并队列
- 通过标签接入第三方合并队列
如果您希望在工作流中使用 Cursor Review，又不想替换现有的合并队列，这种方式会很有用。相比合并队列，代价是分支栈合并速度较慢，错误处理也需要更多手动操作。
将 PR 加入 GitHub 合并队列¶
要合并 PR，请点击 PR 页面右上角的 准备就绪后合并 开关。
当该 PR 是分支栈中第一个处于打开状态的 PR，且 准备就绪后合并 已启用时，Cursor Review 会将其加入您的 GitHub 合并队列。
上层 PR 也可以启用 准备就绪后合并。下层 PR 合入后，它们便会合并。
使用 GitHub 合并队列一次合并一个 PR 时，上层 PR 可能会显示已合并下层 PR 引入的文件或提交。这是预期行为。GitHub 合并 PR 后，会删除已合并的分支，并自动将依赖的 PR 重新定向到基础分支 (例如 main) ，而不会先进行变基。
为缓解此问题，下层 PR 合并后，请在本地运行 gt sync && gt submit，对上层 PR 的分支进行变基。
如果下层 PR 合并前，上层 PR 已在 Cursor Review 中启用 准备就绪后合并，那么下层 PR 合入后，它们会自动变基。
如果是从头开始，请使用合并队列。如果已有暂时无法替换的队列，可通过外部集成作为过渡。
疑难排查¶
PR 绕过了队列¶
检查分支保护规则或规则集。如果其他参与者仍可直接推送到默认分支，就可以绕过队列合并，并导致队列重新启动。
PR 已从队列中移除¶
最常见的原因包括：
- 合并冲突
- 检查失败或其他合并阻塞因素
- 位于队首时超时
- 提交签名要求
变基或解决阻塞因素后，再次入队。
队列已暂停，但 PR 仍不断出现¶
这是预期行为。暂停的队列仍会接受新任务，只会在队列恢复后继续合入。
GitHub 合并队列已启用¶
如果需要与 GitHub 的队列配合使用，请使用外部合并队列集成。
