GitHub 整合
基於 Cursor 官方 GitHub integration 文件解釋 GitHub App、GHES、IP allowlist、Advanced networking、許可權和排障。
📖 本篇術語速查表
| 英文 / 縮寫 | 中文 | 一句話解釋 |
|---|---|---|
| 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 |
註冊 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。