---
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="/zh-Hant/docs/cursor/official/05-integrations-sdk/71-gitlab" />
  <Card title="Bugbot" description="回看 GitHub 接入後如何做自動 PR review。" href="/zh-Hant/docs/cursor/official/04-cloud-agents/55-bugbot" />
</Cards>
