使用 Codex 審查 GitLab 合併請求

使用 Codex 程式碼審查，對 GitLab 合併 請求再進行一輪重點明確且有價值的審查。Codex 會審查合併請求差異、遵循儲存庫 指南，並行布一份重點關注嚴重問題的標準 GitLab 程式碼審查。

GitLab 支援目前處於 beta 階段，適用於所有 ChatGPT 方案。Codex 整合在 Codex cloud 中執行。桌面應用程式中 GitHub 風格的儲存庫控制項（例如 建立拉取請求）不包含在此 beta 版本中。

開始之前

請確保你具備：

• 已連線的 GitLab 帳戶。GitLab.com 需要使用 標準連線流程； 自託管或 Dedicated GitLab 執行個體需要進行 工作區管理員範本設定。
• 如果希望 Codex 遵循儲存庫特定的審查 指南，請準備一個 AGENTS.md 檔案。

設定 Codex 程式碼審查

設定 GitLab 連線和 Codex 審查身分

對於 GitLab.com，請先在 ChatGPT 中連線 GitLab， 然後在 Codex 中連線你的 GitLab 帳戶。 對於自託管或 Dedicated GitLab，每位審查者都應在 工作區管理員範本發布後進行連線。

對於自託管或 Dedicated GitLab，請開啟 Codex Cloud → 設定 → 連接器。 工作區管理員可以讓 Codex 建立服務帳戶，也可以儲存現有 服務帳戶的個人存取令牌。

讓 Codex 建立帳戶

在 Codex Cloud → 設定 → 連接器 中，選擇適用於你的 自託管或 Dedicated GitLab 主機的應用 → 選擇設定服務帳戶 → 建立服務帳戶。完成設定的工作區管理員必須擁有 GitLab 執行個體的管理員存取權限。選擇選定的群組 或僅選定的專案，然後選擇 Codex 應在哪些位置執行並建立 帳戶。群組選項會授予對每個所選群組的 Developer 存取權限， 其專案和子群組會繼承該權限；專案選項只會授予對你所選各個 專案的 Developer 存取權限。Codex 將建立 ChatGPT Codex Connector 執行個體服務帳戶，並為其生成具有 api scope 的個人存取令牌。

使用現有帳戶

在 GitLab 中建立或選擇服務帳戶，並且只在 Codex 應執行的 群組或專案中授予其 Developer 存取權限。在服務 帳戶 頁面中，選擇該帳戶 → 管理存取令牌 → 新增新 令牌，以 建立個人存取令牌， 該令牌須具有 api scope，且到期日期至少在 30 天後。返回 Codex，選擇使用現有服務帳戶，貼上令牌，然後選擇 儲存令牌。令牌在儲存時會被加密，之後不會再次顯示。

管理服務帳戶令牌

工作區管理員可以在 Codex Cloud → 設定 → 連接器 中管理服務帳戶。對於 Codex 建立的帳戶，管理員可以撤銷 當前令牌並生成新令牌。對於現有帳戶，管理員可以在 Codex 中替換或移除已儲存的令牌，並根據需要在 GitLab 中單獨撤銷該令牌。 設定有效令牌之前，Codex 無法回應 GitLab 活動。

選擇如何將 GitLab 活動傳遞給 Codex

為編碼任務或專案特定的設定建立專案環境

在 Codex Cloud → 設定 → 環境 中選擇 GitLab 專案； 當你希望 Codex 為該專案編寫或執行程式碼時，請建立專案環境， 例如編輯檔案、提交變更或向合併請求分支推送更新；如果審查依賴 專案特定的敏感資訊、網路存取權限或設定命令，也應建立專案環境。

對於 GitLab.com，啟用 Codex 審查也需要專案環境。

建立環境時，開啟允許來自 GitLab 的 Codex 活動， 以安裝專案 webhook，將合併請求、評論和議題 事件傳遞給 Codex。建立專案 webhook 需要 Maintainer 或 Owner 存取權限、管理員存取權限，或可管理專案 webhook 的自訂角色。簽名的專案和群組 webhook 要求 GitLab 19.0 或更高版本。在 自託管 GitLab 19.0 上，請確認已啟用 webhook_signing_token 功能開關； 該標誌預設啟用，並已在 GitLab 19.1 中移除。

為 GitLab 群組中的專案啟用 Codex 審查活動

對於自託管或 Dedicated GitLab，工作區管理員可以開啟環境 → GitLab 活動 → 管理群組，在整個群組 及其子群組中啟用 Codex 審查。Codex 將安裝覆蓋該群組 所有專案的群組 webhook。已連線的 GitLab 使用者必須是群組 Owner，且 群組 webhook 需要 GitLab Premium 或 Ultimate 以及 GitLab 19.0 或更高版本。

群組活動會啟用程式碼審查，但不會建立專案環境。 如需執行由 GitLab 觸發的編碼任務，例如編輯檔案、執行命令、 提交變更或向合併請求推送更新，請建立專案 環境。

設定程式碼審查策略

在 Codex 審查設定中設定程式碼審查策略。 選擇你的儲存庫，然後在審查程式碼 下開啟自動審查。 透過審查 選擇對哪些人的合併請求進行審查，並透過觸發條件 選擇何時執行審查。儲存庫設定可以覆蓋個人預設設定。

請求 Codex 審查

1. 在合併請求評論中提及 @codex review。
2. 等待 Codex 作出反應 (👀) 並行布審查。

Codex 會像團隊成員一樣，在合併請求中發布 GitLab 討論和備註。 預設情況下，手動請求的審查可以包含 P0、P1 和 P2 層級的發現，而自動審查重點關注 P0 和 P1 層級的發現。

啟用自動審查

如需自動審查符合條件的合併請求，請在 Codex 設定中開啟自動 審查，選擇 GitLab 儲存庫策略，然後選擇 觸發器：MR 開啟時、每次推送時 或智慧觸發器（實驗性）。 當合併請求事件符合該策略和觸發器時，Codex 無需 @codex review 評論 即可執行。

必須透過專案 webhook 或上級群組 webhook 啟用 GitLab 活動。對於自託管或 Dedicated GitLab，所設定的服務帳戶 還必須擁有向專案寫回內容的權限。如果已設定 專案環境，Codex 會使用該環境。如果上級群組已經啟用 活動，其後代專案會繼承該覆蓋範圍。

自訂 Codex 的審查內容

Codex 會在儲存庫中搜索 AGENTS.md 檔案，並遵循適用的 程式碼審查規則。請在距離規則所約束程式碼最近的檔案中新增 ## Code Review Rules 部分。 在有助於組織內容時，可使用 ### 標題對相關檢查進行分組。

例如，實驗報告服務可以避免曝光後的行為 改變用於比較的實驗群組：

## Code Review Rules

### Experiment cohorts

- Do not filter treatment comparisons on post-exposure behavior, including conversion or retention.
  Safe path: build cohorts from assignment or exposure; report conversion as an outcome.

將適用於整個儲存庫的規則放在根目錄的 AGENTS.md 中，將特定於服務的規則放在 巢狀檔案中，例如 services/experiment_reporting/AGENTS.md。Codex 會對每個變更檔案應用 覆蓋該檔案的根目錄指南和更具體的指南，因此無關 變更無需攜帶服務特定的上下文。

首先編寫兩三條簡潔規則，明確審查者經常需要 解釋的檢查。實用規則包括：

• 聚焦於影響重大的儲存庫特定行為。 說明需要標記的 相容性約束、資料邊界或不安全的副作用，以及 其重要性。
• 說明安全路徑或例外。 為 Codex 提供足夠的上下文，以區分 真實問題與預期行為。
• 確保規則範圍明確且持久。 優先描述預期結果，而不是可能 變化的函式名稱，並將指南放在其所約束程式碼的附近。
• 將機械性檢查留給 CI。 不要在審查規則中加入格式化、lint 和其他 確定性檢查。

開啟一個有代表性的合併請求，並使用 @codex review 請求審查。 根據你看到的發現和回饋完善規則，並縮小或 移除產生噪聲的指南。

程式碼審查規則用於指導 Codex；它們不能取代測試、分支保護或 必要核准。

如需臨時聚焦於某個方面，請將其新增到合併請求評論中：

@codex review for issues in the database migration

處理審查發現

修復審查發現需要已設定的專案環境；僅啟用群組 活動雖可支援審查，但無法執行編碼任務。如果專案已有 環境，可再留一條評論，讓 Codex 在同一個合併請求中修復 問題：

@codex fix the P1 issue

Codex 會以該合併請求為上下文啟動舊版雲端對話，並可 在獲得權限時將修復推送回該分支。

向 Codex 分配其他任務

其他編碼任務也需要已設定的專案環境；僅啟用群組 活動即可支援審查。如果你在評論中提及 @codex，且 內容不是 review，Codex 就會啟動舊版雲端對話，以 你的合併請求為上下文。

@codex fix the CI failures

排查程式碼審查問題

如果 Codex 沒有作出反應或發布審查：

• 確認已選擇預期的 GitLab 應用；如果使用專案特定的 設定，請確認該專案擁有預期的 Codex cloud 環境。
• 確認已為該專案或某個上級群組啟用活動。在 GitLab 中檢查 Webhooks → 最近的事件， 並驗證合併請求和備註是否成功傳遞。
• 對於自託管或 Dedicated GitLab，請確認專案或群組 webhook 已 簽名、已啟用 SSL 驗證，並且執行個體使用 GitLab 19.0 或 更高版本。在自託管 GitLab 19.0 上，請確認已啟用 webhook_signing_token 功能 標誌；修復因失敗而被自動停用的 hook。
• 對於自託管或 Dedicated GitLab，請確認現有服務帳戶的 個人存取令牌處於有效狀態，並具有 api scope。如果服務帳戶由 Codex 建立， 請確認其已在 Codex 連接器設定 中正確設定，並且該專案或群組已啟用。
• 對於自託管或 Dedicated GitLab，請確認工作區服務 帳戶（而不僅僅是已連線的 GitLab 使用者）擁有該專案 或上級群組的 Developer 存取權限，以便 Codex 發布審查和反應。成員資格會 被繼承；活動與服務帳戶存取權限彼此獨立。
• 確認已啟用程式碼審查 或自動審查，並且 MR 符合 儲存庫策略和觸發器。
• 使用 @codex review。