合併隊列讓團隊可以在一處安排 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 的隊列配合使用，請使用外部合併隊列集成。
