Menyiapkan konektor Aplikasi BYO GitHub di Agen SRE Azure

Sambungkan agen Anda ke GitHub dengan menggunakan Bring Your Own GitHub App, identitas layanan yang didaftarkan organisasi Anda dengan kredensial yang didukung Key Vault.

Important

Tutorial ini menyiapkan akses berbasis aplikasi ke repositori GitHub Anda dengan menggunakan Byo GitHub App dengan kredensial yang didukung Key Vault. Semua operasi dikaitkan dengan identitas aplikasi Anda, bukan pengguna individual.

Kapan menggunakan Aplikasi BYO

Gunakan Aplikasi BYO saat:

  • Organisasi Anda memerlukan autentikasi berbasis aplikasi dan kontrol penahanan kunci.
  • Anda tersambung ke *.ghe.com repositori (diperlukan).
  • Anda menginginkan akses berbasis token penginstalan daripada token pengguna.

Prerequisites

  • Menjalankan agen dengan peran Administrator atau Pengguna Standar
  • Aplikasi GitHub yang dibuat pada host target Anda (github.com atau *.ghe.com)
  • GitHub akses admin org atau repositori (untuk membuat, menginstal, atau memverifikasi cakupan aplikasi GitHub)
  • Kunci privat aplikasi yang disimpan di Azure Key Vault sebagai rahasia
  • Identitas terkelola agen dengan peran Key Vault Secrets User pada vault tersebut

Langkah 1: Membuat Aplikasi GitHub

Jika Anda sudah memiliki Aplikasi GitHub dengan izin yang tepat, lewati ke Langkah 2.

  1. Buka host GitHub Anda:
    • github.com: Buka organisasi Anda, lalu pilih Pengaturan>Pengaturan pengembang>Aplikasi GitHub>Aplikasi GitHub baru.
    • <tenant>.ghe.com: Jalur yang sama di instans GHE Anda.
  2. Isi detail aplikasi:
    • GitHub Nama aplikasi: Misalnya, contoso-sre-agent-reader (awalan dengan nama organisasi Anda untuk menghindari konflik).
    • URL halaman beranda: https://sre.azure.com.
    • Webhook: Hapus centang Aktif (agen tidak menggunakan webhook).
  3. Di bawah Izin, atur:
    • Izin repositori > Konten: Baca-saja (diperlukan).
    • Izin repositori > Metadata: Baca-saja (dipilih otomatis).
    • Tambahkan akses baca secara opsional ke Issue dan pull request.
  4. Di bagian Di mana Aplikasi GitHub ini dapat diinstal?, pilih Hanya di akun ini.
  5. Pilih Buat Aplikasi GitHub.
  6. Perhatikan ID Klien yang ditampilkan di halaman Pengaturan aplikasi (dimulai dengan Iv..., ini berbeda dari ID Aplikasi numerik).

Menginstal Aplikasi GitHub

  1. Pada halaman pengaturan aplikasi GitHub, pilih Install App di bilah sisi kiri.
  2. Pilih organisasi Anda.
  3. Pilih Semua repositori atau pilih repositori tertentu.
  4. Pilih Instal.

Langkah 2: Buat kunci privat

  1. Pada halaman pengaturan Aplikasi GitHub, gulir ke kunci Private.
  2. Pilih Buat kunci privat.
  3. Sebuah file .pem diunduh. File ini adalah kunci privat RSA yang digunakan agen untuk mengautentikasi.

Warning

Jaga keamanan PEM. Anda mengunggah kunci ini ke Key Vault di langkah berikutnya. Jangan lakukan commit ke repositori atau membagikannya.

Langkah 3: Simpan kunci privat di Key Vault

  1. Buka portal Azure dan buka Key Vault Anda.
  2. Buka Rahasia>Hasilkan/Impor.
  3. Atur Nama (misalnya, sre-agent-github-app-key) dan tempelkan konten PEM lengkap sebagai Nilai (termasuk -----BEGIN RSA PRIVATE KEY----- dan -----END RSA PRIVATE KEY----- header).
  4. Pilih Buat.
  5. Buka rahasia, pilih versi saat ini, dan salin URI Pengidentifikasi Rahasia :
https://myvault.vault.azure.net/secrets/my-github-app-key/<version>

Tip

Gunakan URI versi (dengan /<version> akhiran) untuk menyematkan ke versi kunci tertentu, atau hilangkan versi untuk selalu menggunakan yang terbaru. Tanpa versi disarankan. Saat Anda memutar kunci, agen secara otomatis mengambil versi baru tanpa memperbarui URI.

Langkah 4: Memberikan akses Key Vault ke identitas agen

  1. Di portal Azure, buka Key Vault Anda dan buka Kontrol akses (IAM).
  2. Tetapkan Key Vault Secrets User ke identitas terkelola agen.
  3. Tunggu penyebaran penetapan peran.

Langkah 5: Mengonfigurasi Aplikasi BYO di Akses Kode

  1. Buka agen Anda.
  2. Buka Builder>Akses Kode.

Cuplikan layar halaman Akses Kode di bawah Navigasi penyusun di Azure Agen SRE.

  1. Pilih Tambahkan repositori.

  2. Pilih GitHub dan masukkan host:

    • github.comuntuk GitHub publik.
    • <tenant>.ghe.com untuk Enterprise Cloud.
  3. Lanjutkan ke Autentikasi.

  4. Pilih Bring Aplikasi GitHub Anda sendiri.

    Cuplikan layar formulir autentikasi Byo GitHub App memperlihatkan ID Klien dan bidang URI Key Vault.

  5. Masuk:

    • ID Pelanggan
    • URI rahasia kunci privat (Key Vault)
    • Identitas Key Vault opsional (atau gunakan yang ditetapkan sistem)
  6. Pilih Sambungkan.

Panduan memvalidasi kredensial Anda. Jika berhasil, Anda akan melihat Connected as GitHub App dengan tanda centang hijau.

Cuplikan layar status berhasil saat terhubung sebagai GitHub App dengan tanda centang hijau.

Note

Jika Anda melihat tanda centang hijau dan Tersambung sebagai Aplikasi GitHub, kredensial Anda valid. Jika Connect gagal, verifikasi ID Klien Anda, Key Vault URI, dan izin identitas terkelola.

Jika Akses Kode tidak terbuka dari navigasi kiri, refresh halaman agen, perluas Builder lagi, dan coba lagi.

Important

Saat Anda memasukkan domain *.ghe.com sebagai host, panduan secara otomatis memilih Gunakan GitHub App Anda sendiri. OAuth dan PAT tidak tersedia untuk host GHE.

Langkah 6: Tambahkan repositori dan verifikasi

  1. Pilih repositori dan simpan.

    Cuplikan layar langkah pemilihan repositori memperlihatkan repositori yang tersedia untuk ditambahkan.

  2. Konfirmasikan kartu Akses Kode memperlihatkan host yang tersambung dan jenis autentikasi GitHubApp.

    Cuplikan layar halaman akses kode memperlihatkan host GitHub yang tersambung dengan jenis autentikasi GitHubApp.

  3. Uji akses kode dalam obrolan:

What files are in the root of owner/repo?

Jika Anda juga memberikan izin Masalah ke Aplikasi GitHub Anda, verifikasi operasi masalah:

List recent issues from owner/repo.

Identitas terkelola per aplikasi

Secara bawaan, agen menggunakan identitas terkelola yang ditetapkan sistem untuk membaca kunci privat dari Key Vault. Jika Anda mengelola beberapa aplikasi GitHub (misalnya, satu per instans GHE), tetapkan identitas terkelola yang ditetapkan pengguna yang berbeda untuk setiap aplikasi. Pendekatan ini memberikan isolasi keamanan karena setiap identitas hanya memiliki akses ke rahasia Key Vault sendiri.

Pilih identitas di menu tarik-turun identitas Key Vault pada Langkah 5.

Dukungan multi-host untuk konektor GitHub

Anda dapat menyambungkan beberapa host GitHub ke agen yang sama. Setiap host memiliki autentikasi independen:

  • github.com: Aplikasi OAuth, PAT, atau BYO
  • contoso.ghe.com: Aplikasi BYO
  • engineering.ghe.com: Aplikasi BYO (dengan Aplikasi GitHub yang berbeda)

Memutuskan sambungan satu host tidak memengaruhi yang lain.

Troubleshooting

Gejala Kemungkinan penyebabnya Perbaiki
Validasi autentikasi gagal ID Klien yang salah atau host yang salah Pastikan aplikasi dibuat di host yang sama seperti yang dimasukkan di Code Access.
Pembacaan rahasia gagal RBAC atau kebijakan akses Key Vault tidak tersedia Berikan Pengguna Rahasia Key Vault ke identitas agen. Jika menggunakan kebijakan akses Key Vault, berikan izin Get untuk rahasia.
Repo menampilkan status Gagal pada Akses Kode Izin aplikasi yang hilang atau cakupan penginstalan Verifikasi Metadata: Baca + Konten: Cakupan baca dan penginstalan.
Masalah obrolan berfungsi tetapi Akses Kode gagal Pemeriksaan titik akhir/jalur berbeda Jalankan ulang pengujian koneksi dan verifikasi izin metadata.