你以为点了连接按钮，仓库就能自动出现在团队列表里？远没那么简单。GitLab.com 这条路径，经常卡在付费方案、权限不够或者仓库同步这几步上；要是用自托管实例，还得额外操心网络通不通、有没有实例级应用、组织边界怎么划。先搞清楚自己该走哪条配置路径，再一项项核对，Cloud Agents 和 Bugbot 才能在授权范围内正常干活。

适用范围：这套操作流程，主要是给团队管理员在网页端配置 Cursor 和 GitLab 对接时用的。走 GitLab.com 路径，需要 Cursor 管理员权限、目标 GitLab 项目的 Maintainer 权限，以及 GitLab 的 Premium 或 Ultimate 版本——GitLab Free 版本不支持这个集成所需的项目访问 token。走自托管路径，则额外要求 Cursor Teams 或企业版、GitLab 实例管理员权限，以及网络连通性。如果你没有对应的角色，别自己硬上，交给组织管理员来处理。

先选 GitLab.com 还是自托管路径

入口位置：打开 Cursor 的 GitLab 官方文档，进入 Settings 板块，你会在 GitLab.com 和 GitLab 自托管两个标签页之间选择。关键动作：根据你仓库实际部署的环境，选择唯一的配置路径——用官方托管服务选 GitLab.com，用团队自建的 GitLab 实例选自托管。

成功标志：团队能明确说清仓库归属的 GitLab 环境，并且为这条路径准备了相应的付费计划和管理员权限。失败处理：如果连仓库域名、实例归属、付费计划都不清楚，先去问 GitLab 管理员确认，别同时跑两套安装步骤，容易混乱。

注意看这张图，GitLab.com 标签页下，先列出了角色和计划限制，后面才是 Connect、Manage、Sync Repos 以及仓库配置的内容。如果你用的是 GitLab Free 版本，就算能看到连接按钮，点再多下也拿不到项目访问 token。

GitLab.com：先核对角色和付费计划

入口位置：Cursor 的团队管理页，以及 GitLab 的项目成员页面。关键动作：首先确认操作者拥有 Cursor 管理员权限和目标 GitLab 项目的 Maintainer 权限，然后检查组织是否使用 Premium 或 Ultimate 版本。

成功标志：在 Cursor 中能进入 Integrations 页面，在 GitLab 项目中能确认自己是 Maintainer 角色，付费方案也支持项目访问 token。失败处理：如果在 Cursor 中找不到集成入口，先去补充管理员权限；GitLab 中角色低于 Maintainer 的，找项目管理员调整权限；如果用的是 Free 方案，先解决付费计划的问题，别把权限不足误认为按钮坏了。

从 Cursor Integrations 发起 GitLab.com 连接

入口位置：打开 Cursor Dashboard，进入 Integrations 页面，找到 GitLab 那一行，点击 Connect。如果之前已经连过，入口名字会变成 Manage Connections。关键动作：从这里进入 GitLab 的安装流程，按照 GitLab 页面的提示，给目标账户或项目范围授权。

成功标志：浏览器跳转到 GitLab 的安装或授权页面，保存后能回到 Cursor 的 Integrations 页面。失败处理：如果页面反复跳转又回到 Cursor，检查浏览器当前登录的 GitLab 账号是否正确、是否拥有 Maintainer 角色、付费计划是否匹配。如果组织策略不允许安装应用，找 GitLab 管理员处理，别反复创建未完成的授权会话，越弄越乱。

官方页面嵌的 Dashboard 截图里，GitLab 和 GitHub、Slack 这些集成是并排的，每一行右边都有管理入口。记得点 GitLab 这一行的入口，别点错进到其他代码托管服务的连接设置里。

安装后同步 GitLab 仓库

入口位置：回到 Cursor Dashboard 的 Integrations 页面，在 GitLab 连接旁边点击 Manage。关键动作：选择 Sync Repos，让 Cursor 重新拉取当前授权范围内的项目和仓库。

成功标志：同步完成后，目标仓库会出现在 Cursor 的可配置仓库列表里。失败处理：如果同步后仓库列表为空，先检查 GitLab 的安装范围和 Maintainer 权限。如果只缺某一个项目，检查这个项目是否在授权范围内，别直接把整条连接都断了。

回到仓库启用 Cloud Agents 或 Bugbot

入口位置：仓库同步完成后，回到 Cursor Dashboard，打开目标仓库的功能配置页。关键动作：只开启团队打算使用的 Cloud Agents 或 Bugbot，然后根据团队制度，核对仓库权限和评审范围是否正确。

成功标志：目标仓库能保存对应的功能设置；Cloud Agents 用于云端任务，Bugbot 用于自动化 PR 评审。失败处理：如果能看到开关但保存失败，回去检查仓库同步和 GitLab 权限的问题。如果连功能都找不到，确认这个仓库是否是从当前 GitLab 连接同步过来的。

自托管环境：先确认计划、网络和实例权限

入口位置：在 Cursor 的 GitLab 官方文档中，切换到 GitLab 自托管标签页，然后打开 GitLab 的实例管理页。关键动作：先确认几件事：Cursor 是 Teams 或企业版，GitLab 方案满足集成要求，操作者拥有实例管理员权限，同时允许来自 Cursor 的安全入站访问，以及 webhook 通知所需的出站访问。

成功标志：付费计划、实例管理员角色、入站路径、出站 webhook 这四项，都能找到对应的负责人确认没问题。失败处理：如果无法开放入站访问，直接看高级网络方案。如果只有项目 Maintainer 权限，没有实例管理员权限，是建不了实例级应用的，必须交给 GitLab 实例管理员来处理。

自托管标签页里，把计划和网络条件放在了创建应用的前面。图中的两个提示框和 Network 列表都是前置门槛，缺一样都不行——后面就算生成了 Application ID 和 Secret，连接也稳不了。

把 Cursor 当前 IP 加入允许列表

入口位置：GitLab 自托管实例的网络或防火墙允许列表里。关键动作：按照 Cursor 当前官方页面列出的地址，将以下三个 IP 加入允许列表：184.73.225.134、3.209.66.12、52.44.113.131。

成功标志：三个地址都加入允许列表，安全团队确认规则只开放了必要的方向和端口。失败处理：如果组织不允许直接添加公网地址，别临时把整个网络范围都放宽，改用 PrivateLink、Cloudflare Tunnel 或反向隧道方案，并重新进行安全评审。

在 GitLab 自托管实例创建应用

入口位置：使用实例管理员账号登录 GitLab 实例，进入应用管理页，新建一个应用。官方建议创建实例级应用。关键动作：将 Redirect URI 填写为 Cursor 官方文档中显示的当前值，设置 Trusted=true、Confidential=true，作用域选择 api 和 write_repository。

成功标志：应用创建完成后显示 Application ID 和 Secret，所有参数与官方页面一一对应。失败处理：如果找不到实例级创建入口，先检查自己的管理员角色是否正确。回调地址不匹配的，从 Cursor 当前官方页面重新复制。作用域少选了一项的，先把应用改对，别拿着凭据反复粘贴试错。

图中的应用参数只有两项布尔设置和两个作用域。Application ID 和 Secret 都是敏感凭据，别放到截图、日志、工单或聊天记录里，正文里也不要出现真实值。

把自托管实例注册到 Cursor

入口位置：打开 Cursor Dashboard，进入 Integrations 页面，展开 Advanced，找到 GitLab Self-Hosted。关键动作：输入 GitLab 实例的主机名，粘贴 Application ID 和 Secret，点击 Register，然后在下拉菜单中选择这个实例，再点击 Connect。

成功标志：实例出现在可选列表中，点击 Connect 后，GitLab 连接显示在 Integrations 页面。失败处理：如果 Register 失败，检查主机名、回调地址和 Secret 是否对应同一个应用。如果实例能选但 Connect 失败，回去检查网络方向、允许列表以及 GitLab 应用的作用域是否正确。

这张图把 Cursor 端的操作路径都集中在一起了：Advanced 反赌册实例，Connect 之后回到 Manage，再运行 Sync Repos。Register 成功只说明实例登记好了，仓库能不能出来，还得看 Connect 和 Sync Repos 是否走通。

为自托管连接同步仓库

入口位置：自托管实例连接成功后，回到 Cursor Integrations 页面，在对应的 GitLab 连接旁边进入 Manage。关键动作：点击 Sync Repos，拉取这个实例中当前授权范围内的仓库。

成功标志：目标仓库出现在 Cursor Dashboard 中，并能进入功能配置页。失败处理：如果实例显示连接成功但仓库列表为空，依次检查应用作用域、实例权限和网络。别重新创建第二个应用，避免搞出多套凭据，导致连接记录混乱。

私网实例：选择 PrivateLink 或 Cloudflare Tunnel

入口位置：在 Cursor 的 GitLab 官方文档中，进入 Advanced Network 板块，展开 AWS PrivateLink 或 Cloudflare Tunnel。关键动作：由企业的网络负责人根据实例位置选择 PrivateLink 或 Cloudflare Tunnel，并与 Cursor 团队协调连接配置。

成功标志：实例能通过私有网络访问，HTTPS、VPC 允许列表以及服务账户访问 token 等安全措施，都有明确的负责人。失败处理：如果团队无法配合进行网络变更，别硬上。官方文档明确指出，目前不支持 Google Private Service Connect，使用这个环境的团队需要先确认好替代方案。

展开的区域里，将适用环境、安全措施和限制都写在一起了。这个方案更适合防火墙后面的 AWS 实例，或者能运行 cloudflared 的环境，可不是点一下就能开的普通开关。

没有入站访问时：使用反向隧道

入口位置：在同一个 Advanced Network 区域里，展开官方文档的第二种隧道方案。关键动作：由企业的网络团队在本地建立一个与 Cursor 服务器的持久 WebSocket 连接，让请求通过隧道转发到 GitLab 实例。

成功标志：实例无需开放入站网络访问，HTTPS 和服务账户访问 token 的边界清晰，持续连接有监控追踪。失败处理：如果连接不稳定，检查本地进程、出站 WebSocket 和服务账户 token。这条路径会增加复杂度和维护成本，如果没有专人维护，别临时上线。

图中的展开内容明确写了适用场景、安全条件和维护成本；下面紧接着就是受保护 Git 范围的内容，提醒你网络通了之后，还得处理组织级的仓库边界问题。

用受保护 Git 范围限制组织边界

入口位置：Cursor 的 Protected Git scopes 配置页，以及 GitLab 的群组或命名空间管理页面。关键动作：将目标 GitLab 群组或命名空间，绑定到正确的 Cursor 组织上。

成功标志：只有目标 Cursor 团队，能通过 Cloud Agents、自动化工具和 Bugbot 使用这个范围内的仓库。失败处理：如果操作者不是 GitLab Owner，别保存绑定。群组名称相似的，先核对完整的命名空间，避免把其他组织的仓库开放给当前 Cursor 团队。

不再使用时：断开 GitLab 账户

入口位置：进入 Cursor Dashboard 的 Integrations 页面，找到对应的 GitLab 连接管理页。关键动作：点击 Disconnect Account，然后按照团队的变更流程，确认这个连接确实不再使用后断开。

成功标志：GitLab 连接回到未连接状态，原来连接的仓库也不会再出现在可配置范围内。失败处理：如果 Cursor 这边断开了，但 GitLab 实例中还保留了应用或 token，由 GitLab 管理员核对是否还有其他团队在使用，再决定是否撤销。别没确认就直接把实例级应用删了。

交给团队使用前，核对这些结果

• 已经明确选择了 GitLab.com 或自托管路径，没有混用两套角色、计划和网络要求。
• 走 GitLab.com 的，已备齐 Cursor 管理员、GitLab Maintainer 权限，以及 Premium 或 Ultimate 版本。
• 走自托管的，已备齐 Cursor Teams 或企业版、GitLab 实例管理员权限，以及入站和 webhook 出站的条件。
• 自托管应用的 Redirect URI、Trusted、Confidential、api 和 write_repository，均按照当前官方页面填写。
• Application ID 和 Secret 未出现在截图、日志、工单或正文中。
• 连接后从 Manage 运行过 Sync Repos，目标仓库能在 Cursor 中进入功能配置页。
• 私网连接或反向隧道，有明确的网络负责人、监控方式和 token 管理边界。
• 受保护 Git 范围由 GitLab Owner 绑定到正确的 Cursor 组织。
• 所需的 Cloud Agents 或 Bugbot 功能，能在授权仓库中保存设置。
• 七张截图都能正常加载，每张只对应一个主要验证点。