---
title: "GitHub 集成"
description: "基于 Cursor 官方 GitHub integration 文档解释 GitHub App、GHES、IP allowlist、Advanced networking、权限和排障。"
verifiedAt: "2026-05-09"
---

GitHub 集成是 Cloud Agents 和 Bugbot 接入 repo 的基础。没有 GitHub App 权限，Cloud Agent 无法 clone、开分支、推 PR，Bugbot 也无法做 PR review。

> [!NOTE]
> **阅读目标**：读完本章，你应该能区分 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。

流程：

1. 打开 Cursor dashboard 的 Integrations。
2. 在 GitHub 旁点击 Connect；已连接则点 Manage Connections。
3. 选择 All repositories 或 Selected repositories。
4. 回到 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：

1. 到 dashboard Integrations -> Advanced -> GitHub Enterprise Server。
2. 输入 GHES base URL，例如 `https://git.yourcompany.com`。
3. 输入 owning organization 名称。
4. 点击 Register。
5. 使用默认推荐名称创建 Cursor Enterprise Application。
6. 到 GHES 的 GitHub Apps 中确认 app 出现。
7. 回到 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](https://cursor.com/docs/integrations/github.md) —— 官方 GitHub.com、GHES、IP allowlist、advanced networking、permissions 和 troubleshooting。
- [Cursor GitHub and GitLab Help](https://cursor.com/help/integrations/github-gitlab.md) —— 官方帮助页。
- [Cursor Cloud Agents](https://cursor.com/docs/cloud-agent.md) —— GitHub 集成支撑的 Cloud Agent。
- [Cursor Bugbot](https://cursor.com/docs/bugbot.md) —— GitHub 集成支撑的 PR review。

## 接下来去哪

<Cards>
  <Card title="GitLab 集成" description="继续学习 GitLab.com 和 self-hosted GitLab 接入。" href="/docs/cursor/official/05-integrations-sdk/71-gitlab" />
  <Card title="Bugbot" description="回看 GitHub 接入后如何做自动 PR review。" href="/docs/cursor/official/04-cloud-agents/55-bugbot" />
</Cards>
