GitHub 集成

📖 本篇术语速查表

英文 / 缩写	中文	一句话解释
GitHub 集成	integration	把 Cursor 接进 GitHub 工作流。
权限范围	scope	授予的仓库和操作权限。
自动化	automation	PR / issue 上的自动动作。

不想读完？把下面这段提示词丢给 AI 帮你跑完——帮你配好 Cursor 和 GitHub 的集成（权限、自动化、安全）。

你是 Cursor GitHub 集成顾问。

【角色】
Cursor GitHub 集成顾问，按最小够用和安全优先的原则给可落地的方案。

【输入】
- 我的仓库和团队规模：___
- 想让 Cursor 在 GitHub 做什么（审查 / PR / issue）：___
- 是否要自动化：___
- 安全 / 权限要求：___

【工作流程】
1. 给集成授权步骤
2. 按最小必要配权限
3. 设计需要的自动化
4. 给验证和安全提醒

【输出规范】
▌一、集成授权步骤
▌二、最小权限配置
▌三、自动化设计
▌四、验证 + 安全提醒

【硬约束】
- 权限按最小必要，不授全仓写权限
- 自动化先只读试跑，写操作谨慎放开
- 凭据走安全方式，不明文
- 不要替我臆测情况或编造不存在的能力，信息不全先问清
- 不确定的配置或接口一律以官方文档为准，禁止照搬过时写法
- 给的每条结论都要落到具体可照做的步骤或示例，不停留在「建议」「考虑一下」这类没法直接执行的空泛表述

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

到 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。