GitLab 整合
基於 Cursor 官方 GitLab integration 文件解釋 GitLab.com、Self-Hosted、paid plan、OAuth app、Sync Repos、網路和排障。
GitLab 整合讓 Cloud Agents 和 Bugbot 可以在 GitLab repositories 和 merge requests 上工作。
閱讀目標：讀完本章，你應該能判斷 GitLab.com 與 self-hosted GitLab 的接入條件，並能配置 Sync Repos、應用許可權和網路路徑。
1. 前置判斷
GitLab 整合比 GitHub 更容易踩 plan 和 token 條件。
| 條件 | 說明 |
|---|---|
| GitLab paid plan | 需要 Premium 或 Ultimate，因為 integration 依賴 project access tokens |
| Cursor admin access | 需要配置 integration |
| GitLab maintainer access | GitLab.com 接入要求 |
| GitLab Self-Hosted | 需要 Cursor Teams 或 Enterprise plan |
| Self-hosted admin | 需要 GitLab instance admin 來建立 application |
如果團隊在 GitLab Free 上，先不要把教程寫成可直接復刻。官方當前說明中，Free 不滿足 project access token 條件。
2. GitLab.com 設定
流程：
- 開啟 Cursor dashboard 的 Integrations。
- 在 GitLab 旁點選 Connect；已連線則點 Manage Connections。
- 按 GitLab installation flow 完成授權。
- 回到 Integrations tab，點選 GitLab connection 旁的 Manage。
- 選擇 Sync Repos。
- 回到 dashboard，在具體 repo 上配置 Cloud Agents 或 Bugbot。
Sync Repos 是關鍵步驟。授權完成但沒同步 repo，後續配置通常會找不到目標 project。
斷開方式：回到 integrations dashboard，點選 Disconnect Account。
3. GitLab Self-Hosted
Self-hosted GitLab 需要：
- paid GitLab plan。
- Cursor Teams 或 Enterprise。
- Cursor 到 GitLab 的 secure inbound access。
- GitLab 到外部的 webhook outbound access。
- GitLab instance admin privileges。
官方推薦 IP allowlisting 時使用：
184.73.225.1343.209.66.1252.44.113.131
如果環境不能直接開放入站，考慮 PrivateLink / Private Service Connect 或 Reverse Proxy Tunnel，企業客戶需要聯絡 Cursor。
4. 建立 GitLab application
在 GitLab instance 建立 application：
| 配置 | 值 |
|---|---|
| Level | Instance level preferred |
| Redirect URI | https://cursor.com/gitlab-connected |
| Trusted | true |
| Confidential | true |
| Scopes | api 和 write_repository |
建立後拿到 Application ID 和 Secret。
然後回到 Cursor：
- dashboard Integrations -> Advanced -> GitLab Self-Hosted。
- 輸入 GitLab hostname。
- 貼上 Application ID 和 Secret。
- 點選 Register。
- 從 dropdown 選擇 GitLab instance。
- 點選 Connect 完成安裝。
- 回到 Integrations tab，Manage -> Sync Repos。
- 回到 dashboard 配置 repo features。
5. Advanced networking
| 方案 | 適合 | 取捨 |
|---|---|---|
| IP whitelisting | 能開放 Cursor inbound 的 self-hosted GitLab | 簡單直觀 |
| PrivateLink / Private Service Connect | 公有云 VPC 中的企業例項 | HTTPS、可選 mTLS、VPC allowlisting、service account tokens |
| Reverse Proxy Tunnel | 無 inbound access 的 on-prem 環境 | 長連線轉發，無需入站，但維護複雜 |
網路方案要和公司安全團隊一起定。不要為了接入 AI 工具臨時繞過 GitLab 入站策略。
6. 接入後能做什麼
| 功能 | GitLab 整合價值 |
|---|---|
| Cloud Agents | clone repo、建立分支、提交改動、處理任務 |
| Bugbot | 在 merge requests 上自動審查 bug、安全問題和質量問題 |
| Security Review | 在 Git-based triggers 上執行安全檢查 |
| Automations | 對 GitLab 相關工作流做後臺 agent run |
不同功能的開關不等同於 GitLab integration 本身。連線後，還要在 dashboard 裡為具體 repo 開啟對應 feature。
7. 常見失敗點
- GitLab 不是 Premium / Ultimate，缺少 project access token 能力。
- self-hosted GitLab 沒有 Cursor Teams / Enterprise。
- OAuth application scope 缺少
api或write_repository。 - redirect URI 寫錯。
- register 後忘了 Sync Repos。
- webhook outbound 被防火牆擋住。
- IP allowlist 只放了 clone 路徑，沒覆蓋 webhook 或 Cursor 訪問路徑。
商業級驗收
上線前至少留下：
- plan 條件截圖或管理員確認。
- GitLab application 配置記錄。
- Sync Repos 後能看到目標 repo。
- 測試 repo 上 Cloud Agent 能建立 branch。
- 測試 MR 上 Bugbot 能執行。
- self-hosted 網路路徑經過安全團隊確認。
- Application ID / Secret 輪換和撤銷流程寫進 SOP。
官方來源
- Cursor GitLab Integration —— 官方 GitLab.com、Self-Hosted、application、networking 和 next steps。
- Cursor GitHub and GitLab Help —— 官方幫助頁。
- Cursor Cloud Agents —— GitLab 整合支撐的 Cloud Agent。
- Cursor Bugbot —— GitLab 整合支撐的 MR review。