設定 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 權限的權杖（classic）並儲存。fine-grained 權杖則需要儲存庫的 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 工作樹中工作的代理一律取得唯讀的 GitHub 權杖。推送會經由 Control Center，它先詢問推送到遠端規則，再用代理從不持有的寫入權杖轉送推送。參見設定沙箱原則
代理所做的提交，作者身分是代理本身——顯示名稱加上 (agent)，位在以代理 id 為鍵的合成位址上——絕不會是真人。提出請求的人則以一筆 Co-Authored-By trailer 記上一筆
設有 GitHub App 時，憑證代理會在每次啟動時簽發細緻、以儲存庫為範圍、約一小時有效的安裝權杖，而不是交出範圍廣泛的權杖。安裝對象是從該次執行所屬儲存庫的 擁有者 解析而來，因此同一個安裝在多個帳號上的應用程式，會正確依該次執行所觸及的帳號界定範圍。沒有應用程式時，代理會收到環境變數中的權杖，它無法縮限為唯讀：此時推送規則能約束 git push，但約束不了直接使用該權杖的程式碼
權杖一律是憑證代理的，絕不是發起請求的成員自己的。對於代表一位既不是擁有者、又尚未連接 GitHub 的成員行事的執行，伺服器的權杖會被扣住

疑難排解

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

這台伺服器上沒有你的 GitHub 憑證。請在程式碼託管下登入或貼上權杖。其他託管平台上的儲存庫不受影響——只有 GitHub 的儲存庫什麼都提供不了。

資料列提供「新增權杖」，卻沒有「以 GitHub 登入」

這台伺服器沒有用戶端 id——這是從原始碼建置時的正常狀態，因為憑證只會內建於官方建置版本中。參見建立 GitHub App：大約只需兩分鐘，而且只有伺服器擁有者需要做一次。

登入對話框顯示供應商未傳回裝置代碼

GitHub App 存在，但它的 Device flow 核取方塊並未勾選。請在應用程式的設定中將它開啟（General → Device flow），然後再試一次。

資料列顯示「透過此伺服器的應用程式」，但我預期看到自己的帳號

你還沒有登入；你看到的是伺服器的應用程式身分在回應。請在該資料列上點擊以 GitHub 登入。

fine-grained PAT 沒有顯示合併按鈕或檢查狀態

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

新增儲存庫時遭到拒絕

註冊必須同時滿足三個條件：路徑位於 git 工作樹內、它設有 origin 遠端，且該遠端指向受支援的託管平台（github.com、gitlab.com 或 bitbucket.org）。參見將儲存庫加入工作區。

大量使用後所有功能會停擺一陣子

那是速率限制的斷路器。GitHub 會以帶著 x-ratelimit-remaining: 0 與重設時間的 403 來表示主要限制；用戶端一看到它，就會在不發出任何網路呼叫的情況下於本機讓後續請求失敗，直到時間窗過去，因此重試風暴無法讓限制加深。暫時性失敗最多會以指數退避重試三次，並遵守 retry-after。