Important
這項 Azure SRE 代理的功能目前正處於預覽階段。 請參閱Microsoft Azure 預覽的補充使用條款,以了解適用於 Azure 測試版、預覽版或其他尚未正式發布的功能的法律條款。
使用 BYO (Bring Your Own) GitHub App,將 GitHub Enterprise Cloud (<TENANT>.ghe.com) 或 github.com 上裝載的存放庫連線到您的 Azure SRE Agent。 代理程式會從你應用程式的私鑰鑄造短暫的安裝權杖,該私鑰儲存在 Azure Key Vault 中,且永遠不會被複製。
Note
BYO GitHub App 同時適用於 github.com 和 *.ghe.com 主機。 關於帶有 OAuth 或 PAT 的 github.com,請參見 Set GitHub connector。
何時使用 BYO GitHub 應用程式認證
以下情況下使用 BYO 應用程式:
- 您的組織需要基於應用程式的認證與金鑰保管控制。
- 你是在連接
*.ghe.com倉庫(必須,因為 GHE 主機無法使用 OAuth 和 PAT)。 - 你要的是以安裝權杖為基礎的存取,而不是使用者權杖。
先決條件
| 需求 | 詳細資料 |
|---|---|
| Azure SRE 代理程式 | 處於 運行中 狀態的代理,具有 管理員 或 標準使用者 角色 |
| GitHub 應用程式 | 在目標主機上建立的GitHub應用程式(github.com 或 <TENANT>.ghe.com) |
| GitHub 管理員存取權 | 組織或倉庫管理員權限以建立、安裝或驗證 GitHub 應用程式範圍 |
| Azure Key Vault | 一個可以儲存 GitHub 應用程式私鑰的保險庫 |
| 受管理的識別 | 能夠將匯入金鑰上的 金鑰保存庫 Crypto User 指派給代理人所使用的身分識別 |
建立一個 GitHub 應用程式
如果你已經有具備正確權限的 GitHub App,可以跳到 將私鑰儲存在 Azure Key Vault。
- 前往你的 GitHub 主機:
-
github.com:前往你的組織 >設定>開發人員設定>GitHub 應用程式>新增 GitHub 應用程式 -
<TENANT>.ghe.com:您 GHE 執行個體上的相同路徑
-
- 填寫應用程式細節:
-
GitHub 應用程式名稱:例如,
sre-agent-reader -
首頁網址:
https://sre.azure.com - Webhook:取消勾選 Active (代理程式不使用 webhooks)
-
GitHub 應用程式名稱:例如,
- 在 權限設定下,設定:
- 儲存庫權限 > 目錄: 唯讀 (必讀)
- 儲存庫權限 > 元資料: 唯讀 (自動選擇)
- 可選擇性地新增 Issues 和 Pull Requests 的讀取權限
- 在此GitHub應用程式可在哪裡安裝?,選擇僅限此帳號。
- 選取 [ 建立 GitHub 應用程式]。
- 請注意應用程式設定頁面上顯示的 客戶端 ID 。
安裝 GitHub 應用程式
- 在GitHub應用程式設定頁面,選擇左側側欄的安裝應用程式。
- 選取您的組織。
- 選擇所有儲存庫或選擇特定儲存庫。
- 選擇 安裝。
產生 GitHub 應用程式的私鑰
- 在GitHub App 設定頁面,捲動到 Private Keys。
- 選擇 產生私鑰。
- 正在下載
.pem檔案。 這個檔案是代理用來驗證的 RSA 私鑰。
注意事項
妥善保管 PEM。 你在下一步就把它上傳到 金鑰保存庫。 不要把它提交到倉庫,也不要分享。
將私密金鑰儲存在 Azure Key Vault 中
將 GitHub App 的私鑰匯入為 RSA 金鑰,而不是祕密,並啟用 Sign 操作。 在匯入前,先將 GitHub 下載的 PEM 轉換成 PKCS#8,然後成功匯入後永久刪除本地的 PEM 檔案。 關於指令,請參見 將私密金鑰儲存在 金鑰保存庫 中。
複製已匯入金鑰的金鑰識別碼 URI:
https://myvault.vault.azure.net/keys/my-github-app-key/<VERSION>
Tip
版本化 URI 與未版本化 URI:你可以使用版本化 URI(加 /<VERSION> 後綴)來固定特定金鑰版本,或省略版本以永遠使用最新版本。 使用未版本化的 URI,這樣當你旋轉金鑰時,代理程式會自動接收新版本,而不必更新 URI。
授與 Agent 身分識別 金鑰保存庫 存取權
- 在Azure入口中,開啟 金鑰保存庫>存取控制(IAM)。
- 將 金鑰保存庫 Crypto User 指派給為 金鑰保存庫 存取所選取的身分識別。 將指派範圍限定為已匯入的金鑰;只有在保存庫專供此應用程式使用時,才可將範圍設為整個保存庫。
- 等待角色分配生效。
在程式碼存取權中設定 BYO 應用程式
- 在入口網站中開啟您的 Agent。
- 前往建置 + 設定>內容>程式碼存取。
- 選擇 新增儲存庫。
- 在連接步驟中,選擇 GitHub,並輸入完整的儲存庫網址,例如
https://<TENANT>.ghe.com/owner/repo。 - 如果有相符的憑證,請在新增存放庫的方式下選擇「新連線」,以設定另一個憑證。
- 在「連線方法」中,選擇「使用你的 GitHub 應用程式」。
- 輸入:
- 用戶端識別碼
-
私鑰 URI(金鑰保存庫):一個
/keys/URI,不是/secrets/URI - 選擇性 金鑰保存庫 身分識別(或保留系統指派)
- 選擇 連線。
巫師會驗證你的憑證。 成功後,你會看到Connected as GitHub App,並標示綠色勾選。
Note
當存放庫 URL 使用 *.ghe.com 主機時,精靈會選取使用您的 GitHub 應用程式。 OAuth 和 PAT 不支援 GHE 主機。
新增儲存庫並驗證連線
- 選擇 「下一步」 以開啟 新增儲存庫,檢視儲存庫條目與顯示名稱,然後選擇 儲存。
- 確認該儲存庫是否出現在程式碼存取清單中,且其連線顯示在連線欄中。
- 在聊天室測試:
Get me recent issues from owner/repo.
多個 GitHub 應用程式的個別應用程式受控識別
預設情況下,代理程式使用系統指派的管理身份進行 金鑰保存庫 簽章操作。 如果你管理多個 GitHub 應用程式(例如每個 GHE 實例一個),你可以為每個應用程式指派不同的 用戶指派的管理身份 。 每個身份只需存取自己的 金鑰保存庫 金鑰。
在設定步驟中,從 金鑰保存庫 身份下拉選單中選擇身份。
GitHub 連線的多主機支援
你可以將多個 GitHub 主機連接到同一個代理程式。 每個主機都有獨立的認證:
-
github.com→ OAuth、PAT 或 BYO 應用程式 -
contoso.ghe.com→ BYO 應用程式 -
engineering.ghe.com→ BYO 應用程式(搭配不同的 GitHub 應用程式)
斷開一台主機不會影響其他主機。
故障排除
| 癥狀 | 可能的原因 | 修復 |
|---|---|---|
| 驗證失敗 | 錯誤的客戶端 ID 或錯誤的主機 | Verify 應用程式是在輸入 Code Access 的同一主機上建立的。 |
| 金鑰保存庫 簽名失敗 | 錯誤的金鑰 URI 或缺少金鑰權限 | 使用啟用 Sign 的 RSA /keys/ URI,並授予所選身份 金鑰保存庫 Crypto User。 |
| Repo 顯示程式碼存取失敗 | 缺少應用程式權限或安裝範圍 | 驗證 Metadata: Read + Contents: Read 及安裝範圍。 |
| 聊天問題可行,但程式碼存取失敗 | 端點/路徑檢查不同 | 重新執行連線測試並驗證元資料權限。 |