---
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="/docs/cursor/official/05-integrations-sdk/72-slack" />
  <Card title="Security Review" description="回看 Git-based security automations。" href="/docs/cursor/official/04-cloud-agents/56-security-review" />
</Cards>
