Einrichten des GitHub-BYO-App-Connectors in Azure SRE Agent

Verbinden Sie Ihren Agenten mit GitHub, indem Sie eine eigene GitHub-App verwenden – eine Dienstidentität, die Ihre Organisation mit durch Key Vault gesicherten Anmeldeinformationen registriert.

Important

In diesem Lernprogramm wird der anwendungsbasierte Zugriff auf Ihre GitHub-Repositorys mithilfe einer eigenen GitHub-App (BYO) mit in Key Vault gespeicherten Anmeldeinformationen eingerichtet. Alle Vorgänge werden Ihrer App-Identität zugeordnet, nicht einem einzelnen Benutzer.

Wann BYO App verwendet werden sollte

Verwenden Sie BYO-App in folgenden Fällen:

• Ihre Organisation erfordert appbasierte Authentifizierung und Schlüsselsicherungskontrollen.
• Sie verbinden sich mit *.ghe.com Repositories (erforderlich).
• Sie möchten den installationsbasierten Zugriff anstelle von Benutzertoken verwenden.

Voraussetzungen

• Ausführen eines Agents mit Administrator- oder Standardbenutzerrolle
• Eine auf Ihrem Zielhost erstellte GitHub-App (github.com oder *.ghe.com)
• GitHub-Organisations- oder Repository-Administratorzugriff (zum Erstellen, Installieren oder Überprüfen des GitHub-App-Berechtigungsumfangs)
• Privater App-Schlüssel, der in Azure Key Vault als geheimer Schlüssel gespeichert ist
• Vom Agent verwaltete Identität mit Schlüsseltresor-Geheimnisbenutzer-Rolle in diesem Tresor

Schritt 1: Erstellen einer GitHub App

Wenn Sie bereits über eine GitHub App mit den richtigen Berechtigungen verfügen, fahren Sie mit Step 2 fort.

1. Wechseln Sie zu Ihrem GitHub-Host:
   • github.com: Wechseln Sie zu Ihrer Organisation, und wählen Sie dann Settings>Developer settings>GitHub Apps>Neue GitHub App.
   • <tenant>.ghe.com: Derselbe Pfad in Ihrer GHE-Instanz.
2. Füllen Sie die App-Details aus:
   • GitHub App-Name: Beispielsweise contoso-sre-agent-reader (Präfix mit dem Namen Ihrer Organisation, um Konflikte zu vermeiden).
   • Homepage-URL: https://sre.azure.com.
   • Webhook: Deaktivieren Sie " Aktiv" (der Agent verwendet keine Webhooks).
3. Legen Sie unter "Berechtigungen" Folgendes fest:
   • Repositoryberechtigungen > Inhalt: Schreibgeschützt (erforderlich).
   • Repositoryberechtigungen > Metadaten: Schreibgeschützt (automatisch ausgewählt).
   • Fügen Sie optional Lesezugriff auf Issues und Pull Requests hinzu.
4. Wählen Sie unter Wo kann diese GitHub App installiert werden? wählen Sie Only auf diesem Konto aus.
5. Wählen Sie "GitHub-App erstellen" aus.
6. Beachten Sie die auf der Seite "App-Einstellungen" angezeigte Client-ID (beginnt mit Iv..., dies unterscheidet sich von der numerischen App-ID).

Die GitHub-App installieren

1. Wählen Sie auf der Seite GitHub App-Einstellungen Install App in der linken Randleiste aus.
2. Wählen Sie Ihre Organisation aus.
3. Wählen Sie "Alle Repositorys" oder "Bestimmte Repositorys" aus.
4. Wählen Sie Installieren aus.

Schritt 2: Generieren eines privaten Schlüssels

1. Scrollen Sie auf der Seite GitHub App-Einstellungen zu Private-Schlüssel.
2. Wählen Sie "Privaten Schlüssel generieren" aus.
3. Eine .pem Datei wird heruntergeladen. Diese Datei ist der private RSA-Schlüssel, den der Agent zur Authentifizierung verwendet.

Warning

Halten Sie das PEM sicher. Sie laden diesen Schlüssel im nächsten Schritt in Key Vault hoch. Checken Sie es nicht in ein Repository ein und geben Sie es nicht weiter.

Schritt 3: Speichern eines privaten Schlüssels in Key Vault

1. Öffnen Sie das Azure-Portal, und wechseln Sie zu Ihrem Key Vault.
2. Wechseln Sie zu "Geheime Schlüssel>generieren/importieren".
3. Legen Sie den Namen fest (z. B sre-agent-github-app-key. ), und fügen Sie den vollständigen PEM-Inhalt als Wert (einschließlich -----BEGIN RSA PRIVATE KEY----- und -----END RSA PRIVATE KEY----- Kopfzeilen) ein.
4. Klicken Sie auf Erstellen.
5. Öffnen Sie das Geheimnis, wählen Sie die aktuelle Version aus und kopieren Sie den Geheimnisbezeichner-URI:

https://myvault.vault.azure.net/secrets/my-github-app-key/<version>

Tip

Verwenden Sie den versionierten URI (mit dem Suffix /<version>), um eine bestimmte Schlüsselversion festzulegen, oder lassen Sie die Version weg, um immer die neueste zu verwenden. Unversioned wird empfohlen. Wenn Sie den Schlüssel drehen, nimmt der Agent die neue Version automatisch auf, ohne den URI zu aktualisieren.

Schritt 4: Gewähren Key Vault Zugriffs auf die Agentidentität

1. Öffnen Sie in Azure Portal Ihre Key Vault, und wechseln Sie zu Access control (IAM).
2. Weisen Sie Key Vault Secrets User der verwalteten Identität des Agents zu.
3. Warten Sie auf die Übertragung der Rollenzuweisung.

Schritt 5: Konfigurieren der BYO-App im Codezugriff

1. Öffnen Sie Ihren Agent.
2. Wechseln Sie zu Builder>Code Access.

1. Wählen Sie "Repositorys hinzufügen" aus.

2. Wählen Sie GitHub aus, und geben Sie den Host ein:

   • github.com für öffentliches GitHub.
   • <tenant>.ghe.com für Enterprise Cloud.

3. Weiter zur Authentifizierung.

4. Wählen Sie Bring Your own GitHub App aus.

   

5. Eingeben:

   • Client-ID
   • URI des Geheimnisses für den privaten Schlüssel (Key Vault)
   • Optionale Key Vault-Identität (oder die systemseitig zugewiesene beibehalten)

6. Wählen Sie Verbinden aus.

Der Assistent überprüft Ihre Anmeldeinformationen. Bei erfolgreicher Ausführung wird Connected als GitHub App mit einem grünen Häkchen angezeigt.

Note

Wenn das grüne Häkchen und Verbindet als GitHub App angezeigt wird, sind Ihre Anmeldeinformationen gültig. Wenn Connect fehlschlägt, überprüfen Sie Ihre Client-ID, Key Vault URI und verwaltete Identitätsberechtigungen.

Wenn sich Code Access nicht über die linke Navigation öffnen lässt, aktualisieren Sie die Agent-Seite, erweitern Sie Builder erneut und versuchen Sie es noch einmal.

Important

Wenn Sie eine *.ghe.com-Domäne als Host eingeben, wählt der Assistent automatisch Bring your own GitHub App aus. OAuth und PAT sind für GHE-Hosts nicht verfügbar.

Schritt 6: Hinzufügen von Repositorys und Überprüfen

1. Wählen Sie Repositories aus und speichern Sie.

   

2. Bestätigen Sie, dass die Codezugriffskarte den verbundenen Host und den Authentifizierungstyp GitHubAppanzeigt.

   

3. Testen des Codezugriffs im Chat:

What files are in the root of owner/repo?

Wenn Sie Ihrer GitHub App auch die Berechtigung für Issues erteilt haben, überprüfen Sie die Issue-Vorgänge:

List recent issues from owner/repo.

Verwaltete Identität pro App

Standardmäßig verwendet der Agent seine system zugewiesene verwaltete Identität, um den privaten Schlüssel aus Key Vault zu lesen. Wenn Sie mehrere GitHub Apps verwalten (z. B. eine pro GHE-Instanz), weisen Sie jeder App eine andere benutzer zugewiesene verwaltete Identität zu. Dieser Ansatz bietet Sicherheitsisolierung, da jede Identität nur Zugriff auf ihr eigenes Key Vault-Geheimnis hat.

Wählen Sie die Identität in der Dropdownliste Key Vault Identität während Schritt 5 aus.

Multihostunterstützung für GitHub Connectors

Sie können mehrere GitHub Hosts mit demselben Agent verbinden. Jeder Host verfügt über eine unabhängige Authentifizierung:

• github.com: OAuth- oder PAT- oder BYO-App
• contoso.ghe.com: BYO-App
• engineering.ghe.com: BYO-App (mit einer anderen GitHub App)

Das Trennen eines Hosts hat keine Auswirkungen auf andere.

Problembehandlung

Symptom	Wahrscheinliche Ursache	Beheben
Fehler bei der Authentifizierungsüberprüfung	Falsche Client-ID oder falscher Host	Überprüfen Sie, ob die App auf demselben Host erstellt wurde, der in Code Access eingegeben wurde.
Fehler beim Lesen des geheimen Schlüssels	Fehlende Key Vault RBAC- oder Zugriffsrichtlinie	Weisen Sie der Agentidentität die Rolle „Schlüsseltresor-Geheimnisbenutzer“ zu. Wenn Sie Key Vault Zugriffsrichtlinien verwenden, erteilen Sie Get Berechtigung für geheime Schlüssel.
Im Repo wird Codezugriff als „Fehlgeschlagen“ angezeigt	Fehlende App-Berechtigungen oder Installationsbereich	Überprüfen Sie Metadaten: Lesen + Inhalt: Lese- und Installationsbereich.
Chat funktioniert, aber der Codezugriff schlägt fehl	Endpunkt-/Pfadüberprüfungen unterscheiden sich	Führen Sie den Verbindungstest erneut aus, und überprüfen Sie die Metadatenberechtigung.