MINARA為 Coding 設定 GitHub 存取
註冊並安裝 GitHub App、設定 Client ID，再讓 Minara 執行 HTTPS Git 與建立 Pull Request
本指南透過儲存庫範圍的 GitHub App 將 Coding 連接到 GitHub。設定完成後， Minara 可以使用已授權的 GitHub 帳號驗證 HTTPS Git 操作並建立 Pull Request。
確認 GitHub remote
確認儲存庫指向 GitHub：
git remote -v[email protected]:owner/repo.git 與 https://github.com/owner/repo.git 均受支援。
Minara 會使用你授權的 GitHub 帳號，透過 HTTPS 完成需要驗證的網路操作，
不會變更 checkout 中設定的 remote。
前置條件
- 可以在個人帳號或組織下建立 GitHub App。
- 可以把 App 安裝到目標儲存庫。組織可能需要 Owner 核准。
- 設定開發版時，需要 Minara Agent 的原始碼 checkout。
1. 註冊 GitHub App
- 開啟 GitHub Settings。
- 選擇 Developer settings。
- 選擇 GitHub Apps。
- 選擇 New GitHub App。
- 選擇目標儲存庫的擁有者。組織儲存庫應優先在該組織下建立 App。
依下表填寫註冊表單：
| 設定 | 值 |
|---|---|
| GitHub App name | 唯一名稱，例如 Minara Coding |
| Homepage URL | 產品、組織或儲存庫 URL |
| Callback URL | 留空。Device Flow 不使用此項 |
| Expire user authorization tokens | 保持開啟 |
| Request user authorization during installation | 保持關閉 |
| Enable Device Flow | 開啟 |
| Webhook Active | 關閉 |
| Where can this GitHub App be installed? | 單一擁有者選 Only on this account，跨帳號安裝選 Any account |
Minara Desktop 在本機發起授權，再由使用者在瀏覽器確認，因此使用 Device Flow。
2. 設定儲存庫權限
在 Repository permissions 中只設定以下權限：
| 權限 | 存取層級 | 用途 |
|---|---|---|
| Contents | Read and write | 透過 HTTPS 擷取和推送 Git 物件 |
| Pull requests | Read and write | 尋找並建立 Pull Request |
| Metadata | Read-only | 讀取儲存庫身分與中繼資料 |
其他儲存庫、組織和帳號權限保持 No access。完成後選擇 Create GitHub App。
3. 把 App 安裝到儲存庫
- 開啟新建 GitHub App 的設定頁。
- 選擇 Install App。
- 選擇目標儲存庫所屬的個人帳號或組織。
- 選擇 Only select repositories。
- 選擇允許 Minara 存取的儲存庫。
- 選擇 Install。如果頁面顯示 Request，需要組織 Owner 核准後才能使用。
安裝負責授予儲存庫存取範圍。之後在 Minara 登入會授權一位使用者透過該安裝執行操作。 兩個步驟都必須完成。
4. 複製 Client ID
返回 GitHub App 設定頁，複製 Client ID。不要複製 App ID。 GitHub App Client ID 通常類似：
Iv1.8a61f9b3a7aba766Client ID 是公開的應用程式中繼資料。Minara 的 Device Flow 不需要 Client Secret， 也不需要 GitHub App private key。
5. 設定 Minara 開發版
在儲存庫根目錄的 .env 中加入 Client ID：
MINARA_GITHUB_APP_CLIENT_ID=Iv1.8a61f9b3a7aba766把範例值替換為 GitHub 頁面中的 Client ID。完全結束並重新啟動 Minara Desktop， 讓 Gateway 在啟動時註冊 provider：
pnpm dev:desktop正式發行版應隨產品提供已設定的公開 Client ID，不應要求每位使用者另行註冊 App。
6. 在 Minara 中連接 GitHub
- 開啟 Minara Settings。
- 選擇 Git 存取權。
- 在 Connect GitHub 下選擇 Connect GitHub。
- Minara 會開啟 GitHub 裝置授權頁，並顯示一次性代碼。
- 輸入代碼、確認 GitHub 帳號，再核准 App。
- 返回 Minara。帳號應顯示 Ready。
驗證
- 確認 GitHub 帳號在 Git 存取權 中顯示 Ready。
- 確認目標 Git remote 透過 SSH 或 HTTPS 指向
github.com。 - 讓 Coding 擷取或推送分支。
- 建立 Pull Request 時，確認 App 已安裝到儲存庫，並擁有 Pull requests: Read and write。
疑難排解
| 現象 | 處理方式 |
|---|---|
| Connect GitHub 無法使用 | 設定 MINARA_GITHUB_APP_CLIENT_ID，再完全重新啟動 Desktop |
| GitHub 提示 Client ID 無效 | 複製 Client ID，不要使用 App ID 或 Client Secret |
| GitHub 沒有顯示裝置授權頁 | 在 GitHub App 註冊頁開啟 Device Flow |
| 授權成功，但儲存庫返回 403 或 404 | 把 App 安裝到該儲存庫，並完成待處理的組織核准 |
| 無法推送 | 把 Contents 設為 Read and write，再核准權限變更 |
| 無法建立 Pull Request | 把 Pull requests 設為 Read and write |
安全模型
- Minara 把使用者 access token 儲存在加密憑證儲存區，不寫入 SQLite 或對話記錄。
- Device code 會過期，而且只能使用一次。
- App 只能存取安裝時選擇的儲存庫。
- 使用者本身的權限和 App 權限會同時生效。
- 中斷 GitHub profile 後，Minara 會刪除已儲存的憑證。