在 Azure SRE Agent 中設定 GitHub BYO App 連接器

透過使用「自帶 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。

  1. 前往你的 GitHub 主機:
    • github.com:進入你的組織,選擇 Settings>Developer settings>GitHub Apps>New GitHub App。
    • <tenant>.ghe.com:在您的 GHE 執行個體上使用相同路徑。
  2. 填寫應用程式細節:
    • GitHub 應用程式名稱:例如,contoso-sre-agent-reader(前綴加上組織名稱以避免衝突)。
    • 首頁網址: https://sre.azure.com。
    • Webhook:取消勾選 Active (代理程式不使用 webhooks)。
  3. 在 權限設定下,設定:
    • 儲存庫權限 > 目錄: 唯讀 (必讀)。
    • 儲存庫權限 > 元資料: 唯讀 (自動選擇)。
    • 可選擇新增 Issues 和 Pull requests 的讀取權限。
  4. 在此GitHub應用程式可在哪裡安裝?,選擇僅限此帳號。
  5. 選取 [ 建立 GitHub 應用程式]。
  6. 請注意應用程式設定頁面上顯示的 客戶端 ID (以 Iv...開頭,這與數字應用程式 ID 不同)。

安裝 GitHub 應用程式

  1. 在GitHub應用程式設定頁面,選擇左側側欄的安裝應用程式。
  2. 選取您的組織。
  3. 選擇「所有儲存庫」或選擇特定儲存庫。
  4. 選擇 安裝。

步驟 2:產生私鑰

  1. 在GitHub App 設定頁面,捲動到 Private Keys。
  2. 選擇 產生私鑰。
  3. 正在下載 .pem 檔案。 這個檔案是代理用來驗證的 RSA 私鑰。

Warning

妥善保管 PEM。 你在下一步將這把金鑰上傳到 金鑰保存庫。 不要把它提交到倉庫或分享。

步驟 3:將私鑰儲存在 金鑰保存庫 中

  1. 打開Azure傳送門,前往你的金鑰保存庫。
  2. 請前往 秘密>產生/匯入。
  3. 設定 名稱 (例如, sre-agent-github-app-key),並將完整的 PEM 內容貼上為 Value (包含 -----BEGIN RSA PRIVATE KEY----- 與 -----END RSA PRIVATE KEY----- 標頭)。
  4. 選取 ,創建。
  5. 打開秘密,選擇目前版本,並複製 秘密識別碼 URI:
https://myvault.vault.azure.net/secrets/my-github-app-key/<version>

Tip

使用帶有 /<version> 後綴的版本化 URI 來釘選特定金鑰版本,或省略該版本以永遠使用最新版本。 建議使用無版本版本。 當你旋轉金鑰時,代理程式會自動接收新版本,且不會更新 URI。

步驟 4:授權 金鑰保存庫 存取代理身份

  1. 在Azure入口網站,打開你的金鑰保存庫,然後進入存取控制(IAM)。
  2. 將 金鑰保存庫 Secrets User 指派給代理管理身份。
  3. 等待角色指派傳播完成。

步驟 5:在 Code Access 中設定 BYO 應用程式

  1. 打開您的 Agent。
  2. 請前往 Builder>程式碼存取。

Azure SRE 代理中建構者導覽下的程式碼存取頁面截圖。

  1. 選擇 新增儲存庫。

  2. 選擇 GitHub 並輸入主持人:

    • github.com 用於公開 GitHub。
    • <tenant>.ghe.com 用於企業雲。
  3. 繼續驗證。

  4. 選擇 自帶GitHub App。

    BYO GitHub 應用程式驗證表單的螢幕擷取畫面,顯示用戶端 ID 和 金鑰保存庫 URI 欄位。

  5. 輸入:

    • 用戶端識別碼
    • 私鑰祕密 URI (金鑰保存庫)
    • 選擇性 金鑰保存庫 身分識別(或保留系統指派)
  6. 選擇 連線。

巫師會驗證你的憑證。 成功後,你會看到Connected as GitHub App,並標示綠色勾選。

 Connected as GitHub App 成功狀態的截圖,並標示綠色勾選。

Note

如果你看到綠色勾勾和已連線為GitHub應用程式,代表你的憑證是有效的。 如果 Connect失敗,請驗證你的客戶端 ID、金鑰保存庫 URI 以及管理身份權限。

如果 Code Access 無法從左側導覽開啟,請重新整理代理頁面,再次展開 Builder ,然後重試。

Important

當你輸入 *.ghe.com 網域作為主機時,精靈會自動選擇 帶上你自己的 GitHub App。 OAuth 和 PAT 不支援 GHE 主機。

步驟 6:新增儲存庫並驗證

  1. 選擇倉庫並存檔。

    儲存庫選擇步驟的截圖,顯示可新增的儲存庫。

  2. 確認 Code Access 卡顯示已連接的主機和認證類型 GitHubApp。

    程式碼存取頁面的螢幕擷取畫面,顯示已連線的 GitHub 主機,且驗證類型為 GitHubApp。

  3. 在聊天中測試程式碼存取權限:

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 及安裝範圍。
聊天問題可行,但程式碼存取失敗 端點/路徑檢查不同 重跑連線測試並驗證元資料權限。