建立 GitHub App

本指南說明如何讓你的伺服器擁有自己的 GitHub 身分。整個過程大約兩分鐘，只有伺服器擁有者需要操作，而且每部伺服器只需做一次。

你可能不需要它

官方建置版本已內建一個 GitHub 用戶端 id，因此以 GitHub 登入無需註冊任何東西即可開箱即用——裝置流程僅憑用戶端 id 就能完成驗證，所以內建它是安全的。當你希望讓伺服器以自身身分行動（webhook、PR 輪詢與工單同步改為在應用程式安裝上執行，而不是靠某個人的憑證），或你正在從原始碼建置時，才需要註冊自己的應用程式。

至於事後連接你自己的帳號，請見設定 GitHub 整合。

為什麼你的伺服器需要自己的應用程式

一次註冊要承擔兩件不同的工作，而應用程式正是讓兩者都名副其實的關鍵：

工作	由什麼來回應	為什麼重要
有人登入	應用程式的用戶端 id，經由裝置流程	你會取得屬於自己的憑證，位於伺服器上，在所有裝置皆通用——無需貼上或輪替任何權杖
伺服器行事	應用程式的 id + 私鑰 → 安裝權杖	webhook、PR 輪詢與工單同步不再取決於某個人的權杖是否仍然有效

注意表格中沒有的東西：用戶端密鑰。GitHub 的裝置流程僅憑用戶端 id 就能完成驗證——無論是裝置代碼請求還是權杖輪詢——因此登入並不需要保存任何密鑰。

若沒有你自己的應用程式，第一件事仍可透過建置版本內建的用戶端 id 運作；第二件事則會回退到伺服器擁有者的憑證，於是背景工作便搭在最先完成初始設定的那個人身上。

沒有「安裝 Control Center 的 GitHub App」這種按鈕

一個分發出去的 GitHub App 意味著所有人共用同一個用戶端密鑰與同一個安裝，如此一來，每個工作區的儲存庫存取都會流經該工作區中沒有人能掌控的憑證。因此每部伺服器都擁有自己的應用程式——本指南要說明的，正是這樣做的代價有多小。

先決條件

• 你是伺服器擁有者——providerApps.* 相關操作僅限擁有者執行，其他人根本看不到這張卡片
• 一個 GitHub 帳號，或一個你可以在其中建立應用程式的組織
• 不需要任何可公開存取的東西：登入採用裝置流程，因此伺服器不需要入站連接埠、隧道、回呼 URL 或網域

註冊應用程式

1. 前往 github.com/settings/apps/new （若為組織：Settings → Developer settings → GitHub Apps → New GitHub App）
2. GitHub App name——隨便填；Control Center (yourname) 就行。它會出現在伺服器所做的提交與留言上
3. Homepage URL——隨便填，例如 https://github.com/your-name
4. Callback URL——留空。裝置流程不需要它
5. 勾選 Enable Device Flow。這是登入絕不可缺少的唯一一項設定
6. 除非你要另外自行串接 webhook，否則取消勾選 Webhook → Active
7. 在 Repository permissions 之下，至少授予：
   • Contents：Read and write
   • Metadata：Read-only（必填）
   • Pull requests：Read and write
   • Issues：Read and write，若你使用 GitHub Issues 來管理工單，以及供機器人搜尋 PR 對話中的留言之用 （請見從 GitHub PR 與 Control Center 對話）
   • Checks：Read-only，用於 PR 頁面上的 CI 狀態
8. 在 Where can this GitHub App be installed? 之下，選擇適合你的那一項——「Only on this account」對個人伺服器而言是正確的選擇
9. 點選 Create GitHub App

收集這三個值

建立完成後，在應用程式頁面上立即取得它們：

值	位置
App ID	General 分頁，靠近頂端
Client ID	General 分頁，「Client secrets」之下
Private key	Generate a private key——會下載一個 .pem 檔

私鑰檔只會下載一次，GitHub 之後不會再顯示它。請保留它直到你貼上為止；你隨時都可以再產生一個。

用戶端密鑰是選填的，而且只換來一件事：若你把「Expire user authorization tokens」保持為 ON，它就是能在背後悄悄更新他人權杖的憑據，而不必每八小時請對方重新登入。登入本身從不使用它。

更簡單的做法是把那項到期設定關閉（OFF），如此一來任何地方都不需要密鑰。若你保持開啟，請產生一組密鑰並貼到 設定 → 伺服器 → 單一登入（供應商應用程式卡片）——它沒有對應的環境變數，也不會內建於任何建置版本中，因此它會留在你的伺服器上。

在你的帳號上安裝它

一個已註冊但未安裝的應用程式可以驗證使用者身分，卻讀不到任何內容。

1. 在應用程式頁面上，開啟 Install App
2. 將它安裝在你的帳號或組織上
3. 選擇 All repositories，或挑選這部伺服器應該看見的儲存庫

將它貼進 Control Center

1. 前往 設定 → 伺服器 → 單一登入，並捲動到供應商應用程式卡片
2. 在 GitHub 區塊中，設定每個欄位：
   • 應用程式 id——數字形式的 App ID
   • 私鑰——貼上完整的 .pem，包含 BEGIN 與 END 行
   • 用戶端 id——取自同一個頁面
   • 用戶端密鑰——僅在你已產生一組時填寫（用於權杖更新）
3. 點選 測試

金鑰會在儲存的當下即被解析，因此被截斷或格式錯誤的貼上內容會立刻遭到拒絕，而不會拖到數小時後才在背景請求中失敗。測試則更進一步，會向 GitHub 查詢該應用程式安裝在哪些帳號上——「已儲存」與「可運作」是兩種不同的說法，只有後者才代表真的有東西會執行。

檢查點：GitHub 區塊顯示「伺服器能以自身身分行動，且人們可以登入」，而 設定 → 工作區 → 個人資料與身分 → 程式碼託管之下的 GitHub 資料列現在會提供以 GitHub 登入。

改用環境變數設定

對於無介面或指令碼化的安裝，伺服器會在某個欄位首次沒有已儲存的值時，從環境變數為它帶入初始值：

GITHUB_APP_ID=123456
GITHUB_APP_PRIVATE_KEY="$(cat control-center.private-key.pem)"
GITHUB_CLIENT_ID=Iv1.0123456789abcdef

這些設定沒有對應的命令列旗標——命令列上的機密可被主機上的每個行程透過 ps 讀取。環境變數是設定它們的唯一地方，而且其優先順序高於建置版本內建的任何值。.env.template 是完整的清單。

在本機開發時，儲存庫根目錄的 .env 會攜帶同樣的值，而桌面應用程式會將它們傳給自己啟動的伺服器。在那裡請把金鑰放在同一行：.env 的值只能是一行，而雙引號內的 \n 會解譯為換行。

GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEow…\n-----END RSA PRIVATE KEY-----"

GITHUB_APP_ID 與 GITHUB_APP_PRIVATE_KEY 正是沙箱權杖仲介已經在讀取的相同名稱，因此一個已設定好精細權限代理權杖的主機，可以免費獲得登入這條路徑。帶入初始值只會在每個欄位各發生一次——之後以已儲存的值為準，所以在設定中的編輯不會被下一次重新啟動覆蓋。

對 Linear 也如法炮製

Linear 沒有裝置流程，因此其登入是一趟瀏覽器來回，而且確實需要一個回呼 URL——供應商應用程式卡片會顯示你應該註冊的確切網址。

1. 在 linear.app/settings/api/applications/new 建立一個 OAuth 應用程式
2. 將 Callback URL 設為卡片顯示的網址，一字不差
3. 將 Client ID 與 Client secret 貼到 Linear 區塊中
4. 可選擇性地新增一組工作區 API key——這是在沒有任何人下指令時，伺服器用來同步工單的憑證

疑難排解

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

應用程式上的 Enable Device Flow 處於關閉狀態。請在 General 之下將它開啟後重試。

測試顯示憑證可用，但應用程式未安裝在任何地方

註冊與安裝是兩個分開的步驟。請在應用程式頁面上開啟 Install App 並安裝它。

測試顯示無法讀取私鑰

請貼上完整的 .pem 檔，包含 -----BEGIN 與 -----END 行。ed25519 或 EC 金鑰無法使用——GitHub App 是以 RSA 簽署。

有成員已登入，卻看不到任何儲存庫

應用程式未安裝在擁有這些儲存庫的帳號上，或其安裝所選取的是其他儲存庫。他們自己的登入只會授予應用程式被允許看見的範圍。

相關指南

• 設定 GitHub 整合
• 從 GitHub PR 與 Control Center 對話
• 連接程式碼託管
• 管理 API 金鑰
• 設定 Slack 整合