---
title: "GitLab 整合"
description: "基於 Cursor 官方 GitLab integration 文件解釋 GitLab.com、Self-Hosted、paid plan、OAuth app、Sync Repos、網路和排障。"
verifiedAt: "2026-05-09"
---

GitLab 整合讓 Cloud Agents 和 Bugbot 可以在 GitLab repositories 和 merge requests 上工作。

> [!NOTE]
> **閱讀目標**：讀完本章，你應該能判斷 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 設定

流程：

1. 開啟 Cursor dashboard 的 Integrations。
2. 在 GitLab 旁點選 Connect；已連線則點 Manage Connections。
3. 按 GitLab installation flow 完成授權。
4. 回到 Integrations tab，點選 GitLab connection 旁的 Manage。
5. 選擇 Sync Repos。
6. 回到 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.134`
- `3.209.66.12`
- `52.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：

1. dashboard Integrations -> Advanced -> GitLab Self-Hosted。
2. 輸入 GitLab hostname。
3. 貼上 Application ID 和 Secret。
4. 點選 Register。
5. 從 dropdown 選擇 GitLab instance。
6. 點選 Connect 完成安裝。
7. 回到 Integrations tab，Manage -> Sync Repos。
8. 回到 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](https://cursor.com/docs/integrations/gitlab.md) —— 官方 GitLab.com、Self-Hosted、application、networking 和 next steps。
- [Cursor GitHub and GitLab Help](https://cursor.com/help/integrations/github-gitlab.md) —— 官方幫助頁。
- [Cursor Cloud Agents](https://cursor.com/docs/cloud-agent.md) —— GitLab 整合支撐的 Cloud Agent。
- [Cursor Bugbot](https://cursor.com/docs/bugbot.md) —— GitLab 整合支撐的 MR review。

## 接下來去哪

<Cards>
  <Card title="Slack 整合" description="繼續學習從 Slack 觸發 Cloud Agents 和配置 repo 路由。" href="/zh-Hant/docs/cursor/official/05-integrations-sdk/72-slack" />
  <Card title="Security Review" description="回看 Git-based security automations。" href="/zh-Hant/docs/cursor/official/04-cloud-agents/56-security-review" />
</Cards>
