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。