GitHub 集成
基于 Cursor 官方 GitHub integration 文档解释 GitHub App、GHES、IP allowlist、Advanced networking、权限和排障。
GitHub 集成是 Cloud Agents 和 Bugbot 接入 repo 的基础。没有 GitHub App 权限，Cloud Agent 无法 clone、开分支、推 PR，Bugbot 也无法做 PR review。
阅读目标：读完本章，你应该能区分 GitHub.com 和 GitHub Enterprise Server 的接入路径，并能解释 repo 权限、IP allowlist 和网络接入方案。
1. 什么时候接 GitHub
| 目标 | 需要 GitHub 集成 |
|---|---|
| Cloud Agent 在 GitHub repo 上开分支、推改动、开 PR | 是 |
| Bugbot 自动 review PR | 是 |
从 issue / PR 评论触发 @cursoragent | 是 |
| Cloud Agent CI failure autofix | 是 |
| 只在本地 Cursor 里编辑代码 | 不一定 |
接入前先决定安装范围：All repositories 还是 Selected repositories。商业团队默认应选 Selected repositories，从低风险 repo 开始验证。
2. GitHub.com 设置
要求：
- Cursor admin access。
- GitHub organization admin access。
流程：
- 打开 Cursor dashboard 的 Integrations。
- 在 GitHub 旁点击 Connect；已连接则点 Manage Connections。
- 选择 All repositories 或 Selected repositories。
- 回到 dashboard，在具体 repo 上配置 Cloud Agents、Bugbot 等功能。
断开方式：回到 integrations dashboard，点击 Disconnect Account。
3. GitHub Enterprise Server
GHES 适合自托管 GitHub 的企业环境。
前置条件：
| 条件 | 说明 |
|---|---|
| GHES version | 官方推荐 v3.8 或更高 |
| Admin privileges | 需要 GHES instance 和目标 organization 的管理员权限 |
| Secure inbound access | Cursor 需要安全访问 GHES |
| Webhook outbound | GHES 需要能向外发 webhook notifications |
注册 Cursor Enterprise App：
- 到 dashboard Integrations -> Advanced -> GitHub Enterprise Server。
- 输入 GHES base URL，例如
https://git.yourcompany.com。 - 输入 owning organization 名称。
- 点击 Register。
- 使用默认推荐名称创建 Cursor Enterprise Application。
- 到 GHES 的 GitHub Apps 中确认 app 出现。
- 回到 Cursor dashboard 配置 repo features。
不要用个人账号作为 owning organization，除非只是临时测试。公司级安装应该由公司 organization 持有。
4. IP allow list
如果组织使用 GitHub IP allow list，Cursor 可以通过 hosted egress proxy 使用一组更窄的 IP。
官方要求：启用此能力前先联系 Cursor 支持打开 feature。
推荐方式：
| 方式 | 说明 |
|---|---|
| Allow access by GitHub Apps | 推荐，Cursor GitHub App 已预配置 IP list，后续更新能自动继承 |
| Direct IP allowlist | 适合 IdP-defined allowlists 或不能使用 GitHub App preconfigured allowlist 的组织 |
如果需要直接加 proxy IP，使用 Cloud Agent Security & Network 页中的 git egress proxy IP。
5. Advanced networking
自托管 GitHub 可以不只靠 IP whitelisting。
| 方案 | 适合 | 取舍 |
|---|---|---|
| IP whitelisting | 可接受安全入站访问的 GHES | 简单，但依赖公网/防火墙策略 |
| PrivateLink / Private Service Connect | AWS / GCP 私有网络中的企业实例 | 企业客户可用，安全边界好，但云环境有要求 |
| Reverse Proxy Tunnel | 无法开放 inbound network access 的 on-prem 环境 | 无需入站，但引入额外组件、维护和安全考虑 |
PrivateLink / Private Service Connect 和 Reverse Proxy Tunnel 都需要联系 Cursor representative。
6. GitHub App 权限
官方列出的权限遵循 least privilege，用于支撑不同功能。
| Permission | Purpose |
|---|---|
| Repository access | clone code、创建 working branches |
| Pull requests | 创建 PR、留下 review comments |
| Issues | 跟踪 Bugbot 或 review 中发现的 bugs / tasks |
| Checks and statuses | 报告 code quality 和 test results |
| Actions and workflows | 监控 CI/CD pipelines 和 deployment status |
权限审计时要把“为什么需要”对应到功能。只用 Bugbot review 时，不要把所有 Cloud Agent 能力都默认放开到所有 repo。
7. 排障
Agent can't access repository：
- GitHub App 是否已安装到该 repo。
- private repo 权限是否覆盖。
- 当前 GitHub account 权限是否匹配。
Permission denied for pull requests：
- GitHub App 是否有 PR write access。
- branch protection rules 是否阻止推送或 PR 操作。
- app installation 是否过期，需要重装。
App not visible in GitHub settings：
- 是否安装在 organization level。
- 是否从
github.com/apps/cursor正确安装。 - installation 是否损坏，需要联系支持。
商业级验收
上线前至少完成：
- Selected repositories 安装范围确认。
- 用测试 repo 验证 Cloud Agent 能开分支和 PR。
- 用测试 PR 验证 Bugbot 能 review。
- GHES 网络路径和 webhook outbound 都可用。
- IP allowlist 或 advanced networking 的所有权、变更流程清楚。
- 权限变更有审计记录。
- Disconnect / reinstall / support escalation 路径写进 SOP。
官方来源
- Cursor GitHub Integration —— 官方 GitHub.com、GHES、IP allowlist、advanced networking、permissions 和 troubleshooting。
- Cursor GitHub and GitLab Help —— 官方帮助页。
- Cursor Cloud Agents —— GitHub 集成支撑的 Cloud Agent。
- Cursor Bugbot —— GitHub 集成支撑的 PR review。