Cursor 自建 GitLab 接不上怎么排查
Cursor 怎么连自建 GitLab？官方支持哪些托管平台、自建实例的前提条件、连不上时按网络、回调、token、权限的顺序排查。
公司代码放在自建 GitLab 上，Cursor 怎么连自建 GitLab 就成了第一道坎。官方文档写了自建实例的接入方式，但前提条件比 GitLab.com 多三条，团队通常卡在其中一条上。
官方支持的平台清单先对一遍
Cursor 文档的 Cloud Agents 页把可连的代码托管写成四条：GitHub（Cloud 与 Enterprise Server）、GitLab（Cloud 与 Self-Hosted）、Bitbucket Cloud、Azure DevOps。括号里那半句就是自建实例问题的答案，GitLab 的自建实例在官方支持范围内，有独立的接入流程和文档章节。
| 平台 | 云端 Agent | Bugbot | 私有或自建实例 |
|---|---|---|---|
| GitHub | 支持 | 支持 | Enterprise Server 支持 |
| GitLab | 支持 | 支持 | Self-Hosted 支持，需 Teams 或 Enterprise |
| Bitbucket | 仅 Cloud | Cloud 与 Data Center | Data Center 只支持 Bugbot |
| Azure DevOps | 支持，public beta | 不支持 | Azure DevOps Server 不支持 |
几条边界值得单独记一下。Azure DevOps 的集成文档写得最死：只支持 dev.azure.com 上的 Azure DevOps Services，Azure DevOps Server 明确不支持，仓库 URL 是 *.visualstudio.com 的还要先换成 dev.azure.com 格式；而且它目前只对 Cloud Agents 生效，Automations、Bugbot、Security Agents 都还没跟上。Bitbucket 则被拆成两套，Bitbucket Cloud 能跑 Cloud Agents 和 Bugbot，Bitbucket Data Center 只支持 Bugbot，Cloud Agents 用不了。
Gitee 不在这份清单里。仓库托管在 Gitee 的团队，走平台集成这条路暂时没有官方入口。
自建 GitLab 的三个硬前提
GitLab 集成文档把门槛写在流程之前，三条都不是靠改配置能绕开的。
GitLab 侧要付费版，Premium 或 Ultimate。原因文档也讲了：这个集成依赖 project access token，而 GitLab Free 不提供这个功能。自建实例装的是社区版的话，这条直接堵死。
Cursor 侧要 Teams 或 Enterprise 套餐。个人 Pro 订阅能连 GitLab.com，但连不了 Self-Hosted 实例，这是文档里单独标注的一行。
操作的人要有 GitLab 实例的管理员权限，因为接入的第一步是在实例里创建一个 application，普通 maintainer 权限做不了。对照一下，连 GitLab.com 只需要 Cursor 管理员加上 GitLab maintainer。
另外还有一条网络前提：自建实例既要接受来自 Cursor 的入站访问，也要能向外发 webhook 通知。两个方向都得通。
建 application 时不能填错的字段
在 GitLab 实例里新建 application，文档建议建在 instance level，四个字段照抄：
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，填实例 hostname、Application ID、Secret，点 Register，再从下拉里选中你的实例，点 Connect。
最后一步最容易漏：回到 Integrations 页，点 GitLab 连接旁边的 Manage，选 Sync Repos。不做这一步，连接状态看着是好的，但仓库列表是空的，回头会误判成权限问题。
云端 agent 和本地 agent 要的不是一套东西
分不清这两层，排查方向会整个跑偏。平台集成是给云端跑的东西用的。Cloud Agents 要 clone 仓库、开分支、推 PR，所以必须由 Cursor 账号的管理员在账号层面接好 SCM，一个人接不上，整个团队都起不来。文档的排障条目写得很直白：agent 起不来先确认已登录并连接了 GitHub、GitLab、Azure DevOps 或 Bitbucket 账号，确认有仓库读写权限，确认自己在付费套餐上。
本地 agent 是另一条路。它在你已经 clone 到本机的工作区里跑，用的是本机的 git 凭据，完全不经过 Cursor 的平台集成。自建 GitLab 只要 git clone 拉得下来、git push 推得上去，本地 agent 就照常干活。想清楚自己要的是哪一种，能省掉一半排查动作。
顺带一提，云端这条路即使连通了，环境没配好照样只能交出半成品，那属于另一层问题，可以看云端 agent 交出半成品 PR 的原因。
连不上时按这个顺序查
网络方向先确认。文档推荐的做法是 IP 白名单，给出三个地址：184.73.225.134、3.209.66.12、52.44.113.131，加进实例的入站允许列表。只放行出站不放行入站，注册那一步就会失败。国内自建实例的公网可达性、企业防火墙会不会放行这三个 IP，取决于你们的网络策略，需要自行验证。
回调地址第二个查。Redirect URI 要严格等于 https://cursor.com/gitlab-connected，多一个斜杠、写成 http、或者填了自家域名，OAuth 环节就断在这。
token 权限第三个查。Scopes 漏掉 write_repository 是高频错误，症状很有迷惑性：仓库能列出来、代码能读，agent 推分支的时候才报权限失败。Trusted 和 Confidential 两个开关也都要是 true。
协议和证书第四个查。走私有网络方案时，文档明确写了不支持自签证书、不支持未加密连接、不支持 SSH、不支持非标准端口、不支持 IPv6-only 的 endpoint service。所以想用 SSH key 连自建实例这条路在这个集成里不成立，只能是 HTTPS 加 443 端口，而且证书得是公开可信的。
实例完全不出公网的团队，Enterprise 套餐下有三种方案：AWS PrivateLink、Cloudflare Tunnel、反向代理隧道。前两种需要和 Cursor 那边对接配置，Google Private Service Connect 目前不提供。客户端这一侧的超时和代理问题是另一条线，参考 Cursor 代理超时排查。
接不上的团队还能怎么干
合规不允许把内网 GitLab 暴露给外部 IP，或者实例还是社区版，平台集成这条路就先放着。本地 agent 不依赖它，在本机工作区里读写文件、跑测试、执行命令都正常，代价是失去云端并行和 PR 自动化。
想要接近云端的体验，可以把开发机放在内网，用 Remote-SSH 连过去，agent 在远端工作区跑。这条路的常见障碍是首次连接时 server 组件下载慢或超时，处理办法见 Remote-SSH 下载超时。
还有一种折中：核心业务仓库留在自建 GitLab 走本地流程，把不敏感的工具库、文档站、脚手架镜像到 GitHub 上接云端 agent。这样能先把云端那套流程跑熟，等采购完 Teams 套餐、网络策略批下来再迁核心仓库。
常见问题
GitLab 社区版能连吗
不能。文档写明集成依赖 project access token，这个功能只在 Premium 和 Ultimate 上提供。装的是 GitLab Free 或社区版的话，先评估升级成本，或者改走本地 agent。
个人 Pro 订阅能连自建实例吗
不能。GitLab Self-Hosted 明确要求 Teams 或 Enterprise 套餐。个人订阅可以连 GitLab.com 的仓库，自建实例这一档没开放。
能不能用 SSH 方式接入
平台集成不行。私有连接相关的文档把 SSH 列在不支持的项里，要求是 HTTPS 加 443 端口加公开可信证书。本地 agent 用你本机的 git 配置，那边用 SSH 是完全没问题的。