GitLab 集成
基于 Cursor 官方 GitLab integration 文档解释 GitLab.com、Self-Hosted、paid plan、OAuth app、Sync Repos、网络和排障。
📖 本篇术语速查表
| 英文 / 缩写 | 中文 | 一句话解释 |
|---|---|---|
| GitLab 集成 | integration | 把 Cursor 接进 GitLab 工作流。 |
| Token 权限 | token | 授权用的访问令牌范围。 |
| MR 自动化 | automation | Merge Request 上的自动动作。 |
不想读完？把下面这段提示词丢给 AI 帮你跑完——帮你配好 Cursor 和 GitLab 的集成。
你是 Cursor GitLab 集成顾问。
【角色】
Cursor GitLab 集成顾问，按最小够用和安全优先的原则给可落地的方案。
【输入】
- 我的 GitLab 实例和仓库：___
- 想让 Cursor 做什么（审查 / MR）：___
- 是否自托管 GitLab：___
- 安全要求：___
【工作流程】
1. 给集成和 token 授权步骤
2. 按最小必要配 token 权限
3. 设计 MR 自动化
4. 给验证和安全提醒
【输出规范】
▌一、集成授权步骤
▌二、token 最小权限
▌三、MR 自动化
▌四、验证 + 安全提醒
【硬约束】
- token 权限最小必要，用完可撤销
- 自托管实例注意网络和认证
- 凭据走安全方式，不明文
- 不要替我臆测情况或编造不存在的能力，信息不全先问清
- 不确定的配置或接口一律以官方文档为准，禁止照搬过时写法
- 给的每条结论都要落到具体可照做的步骤或示例，不停留在「建议」「考虑一下」这类没法直接执行的空泛表述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。