設定 GitHub 整合

本指南涵蓋設定中專屬於 GitHub 的部分。GitHub 是三種受支援的程式碼託管平台之一 —— 連接 GitLab 或 Bitbucket，以及同一個工作區如何混用它們，請參見連接程式碼託管。

先決條件

一個 GitHub 帳戶，且能存取你想處理的程式庫
或者為你的伺服器註冊一個 GitHub App（參見建立 GitHub App），讓你得以登入；或者準備一個帶 repo 和 read:org 權限、可供貼上的個人存取權杖

使用 GitHub 登入

這是一種裝置流程：GitHub 向你顯示一組簡短的代碼，你在 github.com 上批准它，伺服器隨即收到憑證 —— 沒有回呼 URL，沒有連接埠，也沒有任何東西需要對外暴露。只要伺服器有用戶端 ID 就可用，而官方組建已經隨附。

前往 設定 → 工作區 → 個人資料與身分 → 程式碼託管（或新手導引的第一步）
在 GitHub 一列上，按一下 使用 GitHub 登入
對話框會顯示一組八個字元的代碼，並在你的瀏覽器中開啟 github.com/login/device。代碼已經複製到你的剪貼板
貼上代碼，批准該應用程式，然後返回。該列會自行變成「已登入為 your-username」

你可以在瀏覽器中繼續操作期間關閉該對話框 —— 伺服器會持續輪詢，直到代碼過期（約 15 分鐘），所以登入仍然會完成。

或貼上權杖

當伺服器沒有應用程式、應用程式未安裝在你要用的帳戶上，或者你乾脆更想使用 PAT 時，這便是後備方案。

前往 設定 → 工作區 → 個人資料與身分 → 程式碼託管
在 GitHub 一列上，按一下 新增權杖
貼上一個帶 repo 和 read:org 權限的權杖（經典）並儲存。精細權限權杖則需要程式庫的 Contents 和 Pull requests（讀取及寫入），再加上 Checks 和 Actions（讀取）。

權杖會在儲存時即時探測，因此該列能指出它屬於哪個帳戶。按一下 中斷連線 即可將它移除。

檢查點：GitHub 一列顯示「已登入為 your-username」。當應答的憑證不是你的，末尾會標出來源 —— 「透過此伺服器的應用程式」或「來自環境變數」。

整合為你帶來甚麼

功能	運作方式
PR 清單與詳情	由伺服器呼叫 GitHub REST API，以應用程式身分或你自己的憑證
檢查執行	GitHub Checks API
發佈審查	一個需經使用者確認的步驟，會把你的審查發佈到 PR
程式庫註冊	只要檢出副本的 `origin` 遠端指向 github.com —— 或指向 gitlab.com / bitbucket.org —— 就會被接受
代理的 GitHub 存取	憑證仲介會把唯讀權杖以 `GH_TOKEN` / `GITHUB_TOKEN` 注入；推送經由 Control Center
通知提示	伺服器端輪詢你的 GitHub 通知收件箱，觸發「在 pull request 中被提及」與「已請求審查」
使用者個人資料	個人資料懸浮卡，以及按作者篩選 PR

部分路徑在更划算的地方會改用 GraphQL API 而非 REST —— 例如供撰寫 PR 選擇器使用的分支活動，以及決定某則已請求審查通知是否仍在待處理的即時審查狀態。

留意 GitHub 服務中斷

當某個供應商降級時，標題列會顯示一個狀態標籤，涵蓋 GitHub、Claude、OpenAI 和 Kimi。一切正常時它是隱藏的 —— 它的出現是在報告問題，而不是報告沒有問題。

按一下該標籤會開啟一個浮出面板，列出每個供應商的狀態，並帶有一個重新整理按鈕。這些狀態每兩分鐘會自行重新整理。

了解代理在 GitHub 上的行為

在 GitHub worktree 中工作的代理一律取得唯讀的 GitHub 權杖。推送會經由 Control Center，它先詢問推送到遠端規則，再用代理從不持有的寫入權杖轉送推送。參見設定沙箱政策
代理所作的提交以代理的身分署名 —— 顯示名稱加上 (agent)，位址則是以代理的 id 為鍵的合成地址 —— 絕不會以真人身分署名。提出要求的人則透過 Co-Authored-By 尾註記入貢獻
設定好 GitHub App 後，仲介會在每次啟動時簽發精細權限、限定至程式庫、有效期約一小時的安裝權杖，而不是交出一枚權限寬泛的權杖。安裝實例會依該次執行的程式庫擁有者來解析，因此一個安裝在多個帳戶上的應用程式，會正確限定到該次執行所觸及的那一個。沒有應用程式時，代理收到的是環境權杖，它無法縮限為唯讀：此時推送規則能約束 git push，但約束不了直接使用該權杖的程式碼
權杖一律是仲介的，絕不是發起要求的成員自己的。對於代表一位既不是擁有者、又尚未連接 GitHub 的成員行事的執行，伺服器的權杖會被扣起

疑難排解

PR 清單是空的，並顯示 GitHub 尚未連接

你在這部伺服器上沒有任何 GitHub 憑證。請在程式碼託管下登入或貼上權杖。其他程式碼託管平台上的程式庫不受影響 —— 只有 GitHub 的程式庫不會貢獻任何內容。

該列提供「新增權杖」，但沒有「使用 GitHub 登入」

伺服器沒有用戶端 ID —— 這是從原始碼組建的常態，因為憑證只會烘焙進官方組建。參見建立 GitHub App：大約只需兩分鐘，而且只有伺服器擁有者需要動手，做一次即可。

登入對話框顯示供應商沒有回傳裝置碼

GitHub App 存在，但其 Device flow 核取方塊處於關閉狀態。請在該應用程式的設定中（General → Device flow）將它開啟，然後重試。

該列顯示「透過此伺服器的應用程式」，但我預期的是自己的帳戶

你尚未登入；你看到的是伺服器的應用程式身分在應答。請在該列按一下 使用 GitHub 登入。

精細權限 PAT 不顯示合併按鈕或檢查狀態

該權杖需要 Contents 和 Pull requests（讀取及寫入），再加上 Checks 和 Actions（讀取）。更改之後，請在程式碼託管下重新貼上。

加入程式庫被拒

註冊需要同時滿足以下三項：路徑位於 git 工作樹內、它有一個 origin 遠端，而且該遠端指向受支援的程式碼託管平台（github.com、gitlab.com 或 bitbucket.org）。參見將程式庫加入工作區。

大量使用後，一切都會停擺一陣子

那是速率限制的斷路器。GitHub 以帶有 x-ratelimit-remaining: 0 的 403 及一個重置時間來表示已達主要限制；用戶端一旦看到，就會在該時窗過去前，令後續請求在本機失敗，不發出網絡呼叫，因此重試風暴無法加深限制。暫時性失敗會以指數退避最多重試三次，並遵循 retry-after。