Konfigurowanie łącznika GitHub BYO App w agencie Azure SRE

Połącz agenta z usługą GitHub przy użyciu aplikacji Bring Your Own GitHub App, tożsamości usługi zarejestrowanej przez organizację przy użyciu poświadczeń opartych na Key Vault.

Ważna

W tym samouczku opisano, jak skonfigurować dostęp do repozytoriów GitHub za pomocą własnej aplikacji GitHub (BYO) z poświadczeniami przechowywanymi w usłudze Key Vault. Wszystkie operacje są przypisywane tożsamości aplikacji, a nie indywidualnemu użytkownikowi.

Kiedy używać aplikacji BYO

Użyj aplikacji BYO, gdy:

  • Twoja organizacja wymaga uwierzytelniania opartego na aplikacji i kontroli nadzoru kluczy.
  • Nawiązujesz połączenie z *.ghe.com repozytoriami (wymagane).
  • Chcesz uzyskać dostęp oparty na tokenach instalacji, a nie tokeny użytkownika.

Wymagania wstępne

  • Uruchamianie agenta z rolą Administrator lub Użytkownik standardowy
  • Aplikacja GitHub utworzona na hoście docelowym (github.com lub *.ghe.com)
  • Dostęp administratora do organizacji lub repozytorium w serwisie GitHub (aby utworzyć, zainstalować lub zweryfikować zakres uprawnień aplikacji GitHub)
  • Klucz prywatny aplikacji przechowywany w Azure Key Vault jako klucz tajny
  • Tożsamość zarządzana agenta z rolą Key Vault Secrets User w tym magazynie kluczy

Krok 1. Tworzenie aplikacji GitHub

Jeśli masz już aplikację GitHub z odpowiednimi uprawnieniami, przejdź do Krok 2.

  1. Przejdź do hosta GitHub:
    • github.com: Przejdź do organizacji, a następnie wybierz Settings>Developer settings>GitHub Apps>New GitHub App.
    • <tenant>.ghe.com: Ta sama ścieżka jak na instancji GHE.
  2. Wypełnij szczegóły aplikacji:
    • GitHub Nazwa aplikacji: na przykład contoso-sre-agent-reader (prefiks z nazwą organizacji, aby uniknąć konfliktów).
    • Adres URL strony głównej: https://sre.azure.com.
    • Webhook: odznacz Aktywne (agent nie używa webhooków).
  3. W obszarze Uprawnienia ustaw:
    • Uprawnienia > repozytorium Zawartość: tylko do odczytu (wymagane).
    • Uprawnienia > repozytorium Metadane: tylko do odczytu (wybrane automatycznie).
    • Opcjonalnie dodaj dostęp do odczytu do Issues i Pull requests.
  4. W obszarze Gdzie można zainstalować tę aplikację GitHub? wybierz pozycję Only na tym koncie.
  5. Wybierz pozycję Utwórz aplikację GitHub.
  6. Zanotuj identyfikator klienta wyświetlany na stronie Ustawienia aplikacji (zaczyna się od Iv..., różni się to od numerycznego identyfikatora aplikacji).

Instalowanie aplikacji GitHub

  1. Na stronie GitHub Ustawienia aplikacji wybierz pozycję Zainstaluj aplikację na lewym pasku bocznym.
  2. Wybierz organizację.
  3. Wybierz pozycję Wszystkie repozytoria lub wybierz określone repozytoria.
  4. Wybierz Zainstaluj.

Krok 2. Generowanie klucza prywatnego

  1. Na stronie ustawień aplikacji GitHub przewiń do Klucze prywatne.
  2. Wybierz pozycję Wygeneruj klucz prywatny.
  3. Pobierany jest .pem plik. Ten plik jest kluczem prywatnym RSA używanym przez agenta do uwierzytelniania.

Warning

Przechowuj plik PEM w bezpiecznym miejscu. Ten klucz należy przekazać do Key Vault w następnym kroku. Nie zatwierdzaj go w repozytorium ani nie udostępniaj go.

Krok 3. Przechowywanie klucza prywatnego w Key Vault

  1. Otwórz portal Azure i przejdź do Key Vault.
  2. Przejdź do pozycji Wpisy tajne>Generuj/Importuj.
  3. Ustaw nazwę (na przykład sre-agent-github-app-key) i wklej pełną zawartość PEM jako wartość (w tym -----BEGIN RSA PRIVATE KEY----- i -----END RSA PRIVATE KEY----- nagłówki).
  4. Wybierz Utwórz.
  5. Otwórz klucz tajny, wybierz bieżącą wersję i skopiuj identyfikator URI Secret Identifier:
https://myvault.vault.azure.net/secrets/my-github-app-key/<version>

Tip

Użyj URI z numerem wersji (z sufiksem /<version>), aby przypisać konkretną wersję klucza, lub pomiń numer wersji, aby zawsze używać najnowszej. Zalecane jest ustawienie „bez wersji”. Po rotacji klucza agent automatycznie pobiera nową wersję bez aktualizowania identyfikatora URI.

Krok 4. Udzielanie Key Vault dostępu do tożsamości agenta

  1. W portalu Azure otwórz Key Vault i przejdź do pozycji Kontrolka dostępu (IAM).
  2. Przypisz rolę Key Vault Secrets User do tożsamości zarządzanej agenta.
  3. Poczekaj na propagację przypisania roli.

Krok 5. Konfigurowanie aplikacji BYO w programie Code Access

  1. Otwórz agenta.
  2. Przejdź do pozycji Builder>Dostęp do kodu.

Zrzut ekranu strony Code Access w nawigacji Builder w Azure SRE Agent.

  1. Wybierz pozycję Dodaj repozytoria.

  2. Wybierz GitHub i wprowadź hosta:

    • github.com dla publicznego GitHuba.
    • <tenant>.ghe.com dla chmury korporacyjnej.

  3. Przejdź do uwierzytelniania.

  4. Wybierz Użyj własnej aplikacji GitHub.

    oekt ekranu przedstawiający formularz uwierzytelniania aplikacji BYO GitHub z polami identyfikatora klienta i identyfikatora URI Key Vault.

  5. Wpisz:

    • identyfikator klienta
    • Identyfikator URI klucza prywatnego (Key Vault)
    • Opcjonalna tożsamość Key Vault (lub zachowaj przypisaną przez system)

  6. Wybierz Połącz.

Kreator weryfikuje dane logowania. Jeśli operacja się powiedzie, zobaczysz Połączono jako aplikacja GitHub z zielonym znacznikiem wyboru.

Zrzut ekranu przedstawiający stan „Połączono jako aplikację GitHub” z zielonym znacznikiem wyboru.

Note

Jeśli zobaczysz zielony znacznik wyboru i Połączono jako aplikacja GitHub, poświadczenia są prawidłowe. Jeśli Connect nie powiedzie się, sprawdź identyfikator klienta, URI usługi Key Vault i uprawnienia tożsamości zarządzanej.

Jeśli Code Access nie otwiera się z lewego panelu nawigacyjnego, odśwież stronę agenta, ponownie rozwiń Builder i spróbuj jeszcze raz.

Ważna

Po wprowadzeniu domeny *.ghe.com jako hosta kreator automatycznie wybiera opcję Użyj własnej aplikacji GitHub. OAuth i PAT nie są dostępne dla hostów GHE.

Krok 6. Dodawanie repozytoriów i weryfikowanie

  1. Wybierz repozytoria i zapisz.

    Zrzut ekranu przedstawiający krok wyboru repozytorium przedstawiający dostępne repozytoria do dodania.

  2. Upewnij się, że karta Dostęp do kodu wyświetla podłączony host i typ GitHubAppuwierzytelnienia.

    Zrzut ekranu strony dostępu do kodu przedstawiający połączony host GitHub z typem uwierzytelniania GitHubApp.

  3. Przetestuj dostęp do kodu na czacie:

What files are in the root of owner/repo?

Jeśli udzielono ci również uprawnień Issues do aplikacji GitHub, sprawdź operacje dotyczące problemów:

List recent issues from owner/repo.

Tożsamość zarządzana dla aplikacji

Domyślnie agent używa przypisanej przez system tożsamości zarządzanej do odczytu klucza prywatnego z Key Vault. Jeśli zarządzasz wieloma GitHub Apps (na przykład po jednej dla każdego wystąpienia GHE), przypisz do każdej aplikacji inną tożsamość zarządzaną przypisaną przez użytkownika. Takie podejście zapewnia izolację bezpieczeństwa, ponieważ każda tożsamość ma dostęp tylko do własnego sekretu w usłudze Key Vault.

Wybierz tożsamość na liście rozwijanej Key Vault identity w kroku 5.

Obsługa wielu hostów dla łączników GitHub

Możesz połączyć wiele hostów GitHub z tym samym agentem. Każdy host ma niezależne uwierzytelnianie:

  • github.com: OAuth, PAT lub BYO App
  • contoso.ghe.com: Aplikacja BYO
  • engineering.ghe.com: aplikacja BYO (z inną aplikacją GitHub)

Rozłączanie jednego hosta nie ma wpływu na innych.

Troubleshooting

Objaw Prawdopodobna przyczyna Napraw.
Sprawdzanie poprawności uwierzytelniania kończy się niepowodzeniem Nieprawidłowy identyfikator klienta lub nieprawidłowy host Sprawdź, czy aplikacja została utworzona na tym samym hoście wprowadzonym w programie Code Access.
Odczyt sekretu nie powiódł się Brak mechanizmu RBAC lub zasad dostępu usługi Key Vault Udziel użytkownikowi wpisów tajnych Key Vault tożsamości agenta. Jeśli używasz zasad dostępu usługi Key Vault, przyznaj uprawnienie Get do wpisów tajnych.
Repo pokazuje „Niepowodzenie” w sekcji Dostęp do kodu Brak uprawnień aplikacji lub brak zakresu instalacji Weryfikacja metadanych: odczyt + Zawartość: odczyt i zakres instalacji.
Problemy z czatem działają, ale dostęp do kodu kończy się niepowodzeniem Kontrole punktu końcowego/ścieżki różnią się Uruchom ponownie test połączenia i zweryfikuj uprawnienie metadanych.
  • Ostatnia aktualizacja o