透過使用「自帶 GitHub 應用程式」將您的代理連接到 GitHub,該服務身份是您的組織以 金鑰保存庫 支持的憑證註冊的。
Important
本教學將使用自備的 (BYO) GitHub App 與以 金鑰保存庫 為後盾的認證,設定透過應用程式存取你的 GitHub 存放庫。 所有操作都歸因於你的應用程式身份,而非個別使用者。
何時使用 BYO 應用程式
以下情況下使用 BYO 應用程式:
- 您的組織需要基於應用程式的認證與金鑰保管控制。
- 你正在連接
*.ghe.com儲存庫(必須)。 - 你要的是以安裝權杖為基礎的存取,而不是使用者權杖。
先決條件
- 以管理員或標準使用者角色執行代理程式
- 在目標主機上建立的GitHub應用程式(
github.com或*.ghe.com) - GitHub 組織或倉庫管理員權限(用於建立、安裝或驗證 GitHub 應用程式範圍)
- 作為秘密儲存在 Azure Key Vault 中的應用程式私密金鑰
- Agent 受控識別,在該保存庫上具有金鑰保存庫秘密使用者角色
步驟 1:建立 GitHub 應用程式
如果你已經有符合權限的 GitHub App,可以跳到 Step 2。
- 前往你的 GitHub 主機:
-
github.com:進入你的組織,選擇 Settings>Developer settings>GitHub Apps>New GitHub App。 -
<tenant>.ghe.com:在您的 GHE 執行個體上使用相同路徑。
-
- 填寫應用程式細節:
-
GitHub 應用程式名稱:例如,
contoso-sre-agent-reader(前綴加上組織名稱以避免衝突)。 -
首頁網址:
https://sre.azure.com。 - Webhook:取消勾選 Active (代理程式不使用 webhooks)。
-
GitHub 應用程式名稱:例如,
- 在 權限設定下,設定:
- 儲存庫權限 > 目錄: 唯讀 (必讀)。
- 儲存庫權限 > 元資料: 唯讀 (自動選擇)。
- 可選擇新增 Issues 和 Pull requests 的讀取權限。
- 在此GitHub應用程式可在哪裡安裝?,選擇僅限此帳號。
- 選取 [ 建立 GitHub 應用程式]。
- 請注意應用程式設定頁面上顯示的 客戶端 ID (以
Iv...開頭,這與數字應用程式 ID 不同)。
安裝 GitHub 應用程式
- 在GitHub應用程式設定頁面,選擇左側側欄的安裝應用程式。
- 選取您的組織。
- 選擇「所有儲存庫」或選擇特定儲存庫。
- 選擇 安裝。
步驟 2:產生私鑰
- 在GitHub App 設定頁面,捲動到 Private Keys。
- 選擇 產生私鑰。
- 正在下載
.pem檔案。 這個檔案是代理用來驗證的 RSA 私鑰。
Warning
妥善保管 PEM。 你在下一步將這把金鑰上傳到 金鑰保存庫。 不要把它提交到倉庫或分享。
步驟 3:將私鑰儲存在 金鑰保存庫 中
- 打開Azure傳送門,前往你的金鑰保存庫。
- 請前往 秘密>產生/匯入。
- 設定 名稱 (例如,
sre-agent-github-app-key),並將完整的 PEM 內容貼上為 Value (包含-----BEGIN RSA PRIVATE KEY-----與-----END RSA PRIVATE KEY-----標頭)。 - 選取 ,創建。
- 打開秘密,選擇目前版本,並複製 秘密識別碼 URI:
https://myvault.vault.azure.net/secrets/my-github-app-key/<version>
Tip
使用帶有 /<version> 後綴的版本化 URI 來釘選特定金鑰版本,或省略該版本以永遠使用最新版本。
建議使用無版本版本。 當你旋轉金鑰時,代理程式會自動接收新版本,且不會更新 URI。
步驟 4:授權 金鑰保存庫 存取代理身份
- 在Azure入口網站,打開你的金鑰保存庫,然後進入存取控制(IAM)。
- 將 金鑰保存庫 Secrets User 指派給代理管理身份。
- 等待角色指派傳播完成。
步驟 5:在 Code Access 中設定 BYO 應用程式
- 打開您的 Agent。
- 請前往 Builder>程式碼存取。
選擇 新增儲存庫。
選擇 GitHub 並輸入主持人:
-
github.com用於公開 GitHub。 -
<tenant>.ghe.com用於企業雲。
-
繼續驗證。
選擇 自帶GitHub App。
輸入:
- 用戶端識別碼
- 私鑰祕密 URI (金鑰保存庫)
- 選擇性 金鑰保存庫 身分識別(或保留系統指派)
選擇 連線。
巫師會驗證你的憑證。 成功後,你會看到Connected as GitHub App,並標示綠色勾選。
Note
如果你看到綠色勾勾和已連線為GitHub應用程式,代表你的憑證是有效的。 如果 Connect失敗,請驗證你的客戶端 ID、金鑰保存庫 URI 以及管理身份權限。
如果 Code Access 無法從左側導覽開啟,請重新整理代理頁面,再次展開 Builder ,然後重試。
Important
當你輸入 *.ghe.com 網域作為主機時,精靈會自動選擇 帶上你自己的 GitHub App。 OAuth 和 PAT 不支援 GHE 主機。
步驟 6:新增儲存庫並驗證
What files are in the root of owner/repo?
若您也為 GitHub App 授予了 Issues 權限,請驗證問題相關操作:
List recent issues from owner/repo.
每個應用程式的受控識別
預設情況下,代理會使用其系統指派的管理身份從金鑰保存庫讀取私鑰。 如果你管理多個 GitHub 應用程式(例如每個 GHE 實例一個),請為每個應用程式指派不同的 用戶指派的管理身份。 此方法提供安全隔離,因為每個身份只能存取自己的 金鑰保存庫 秘密。
在第 5 步的 金鑰保存庫 identity下拉選單中選擇該身份。
GitHub 連接器的多主機支援
你可以將多個 GitHub 主機連接到同一個代理程式。 每個主機都有獨立的授權:
-
github.com: OAuth、PAT 或 BYO 應用程式 -
contoso.ghe.com: BYO 應用程式 -
engineering.ghe.com:BYO 應用程式 (搭配不同的 GitHub 應用程式)
斷開一台主機不會影響其他主機。
Troubleshooting
| 癥狀 | 可能的原因 | 修復 |
|---|---|---|
| 驗證失敗 | 錯誤的客戶端 ID 或錯誤的主機 | Verify 應用程式是在輸入 Code Access 的同一主機上建立的。 |
| 機密讀取失敗 | 缺少 金鑰保存庫 RBAC 或存取原則 | 將金鑰保存庫秘密使用者授與 Agent 身分識別。 若使用 金鑰保存庫 存取政策,請授予 Get 秘密權限。 |
| Repo 顯示程式碼存取失敗 | 缺少應用程式權限或安裝範圍 | 驗證 Metadata: Read + Contents: Read 及安裝範圍。 |
| 聊天問題可行,但程式碼存取失敗 | 端點/路徑檢查不同 | 重跑連線測試並驗證元資料權限。 |