Cara Menghubungkan Repositori GHE.com ke Apidog

Apidog dapat terhubung ke tenant residensi data GitHub Enterprise Cloud yang di-hosting pada domain *.ghe.com khusus. Setelah Administrator Organisasi mengonfigurasi tenant dan Aplikasi OAuth, pengguna proyek yang berwenang dapat menghubungkan repositori dan menggunakan alur kerja impor, pencadangan, dan sinkronisasi OpenAPI yang didukung.

Integrasi ini untuk tenant SaaS residensi data GitHub Enterprise Cloud. Ini tidak mendukung GitHub Enterprise Server atau domain GitHub khusus lainnya.

Sebelum Anda memulai

Anda memerlukan:

• organisasi Apidog Enterprise dengan akses ke integrasi
• izin Administrator Organisasi di Apidog
• tenant residensi data GitHub Enterprise Cloud pada domain *.ghe.com root, seperti https://company.ghe.com
• izin untuk membuat Aplikasi OAuth pada tenant tersebut
• akses ke organisasi, repositori, dan cabang GitHub yang ingin Anda hubungkan

Pengguna yang menghubungkan repositori juga harus memiliki izin koneksi Git tingkat proyek yang relevan di Apidog.

Langkah 1: Buat Aplikasi OAuth di tenant GHE.com

1. Masuk ke tenant GHE.com organisasi Anda.
2. Buka pengaturan Aplikasi OAuth.
3. Buat Aplikasi OAuth baru.
4. Masukkan nama aplikasi yang mudah diidentifikasi.
5. Atur URL beranda menjadi:https://apidog.com
6. Atur URL callback otorisasi menjadi:https://api.apidog.com/passport/github/callback
7. Daftarkan Aplikasi OAuth.
8. Salin Client ID.
9. Buat dan salin Client Secret dengan aman.

URL callback harus sama persis dengan URL Apidog yang didokumentasikan.

Simpan Client Secret di sistem manajemen rahasia Anda yang disetujui. Jangan letakkan di tangkapan layar, tiket, atau dokumen bersama.

Langkah 2: Konfigurasi tenant GHE.com di Apidog

Hanya Administrator Organisasi yang dapat mengonfigurasi atau menghapus integrasi ini.

1. Buka organisasi Apidog.
2. Pergi ke Pengaturan Organisasi.
3. Buka Integrasi GitHub.
4. Temukan Residensi Data GitHub Enterprise Cloud dan pilih Konfigurasi.

• Masukkan URL host GHE.com, misalnya https://company.ghe.com.
• Pilih Aplikasi OAuth sebagai metode otentikasi.
• Masukkan Client ID Aplikasi OAuth.
• Masukkan Client Secret Aplikasi OAuth.
• Simpan konfigurasi.

Konfigurasikan host tenant dan kredensial Aplikasi OAuth di tingkat organisasi.

Setelah menyimpan, Apidog menampilkan URL host yang dikonfigurasi. Client Secret tidak ditampilkan atau diisi ulang lagi.

Ketika mengedit konfigurasi di kemudian hari, membiarkan kolom Client Secret kosong akan mempertahankan rahasia yang ada. Masukkan nilai baru hanya saat merotasinya.

Langkah 3: Hubungkan repositori dari proyek Apidog

Setelah konfigurasi tingkat organisasi selesai:

1. buka proyek Apidog yang diperlukan;
2. mulai koneksi Git atau alur kerja impor Git;
3. pilih GitHub Enterprise Cloud;
4. lanjutkan ke halaman otorisasi di tenant GHE.com yang dikonfigurasi;
5. masuk dan otorisasi Aplikasi OAuth;
6. pilih organisasi GitHub;
7. pilih repositori dan cabang;
8. selesaikan koneksi.

Otorisasi dilakukan pada tenant GHE.com yang dikonfigurasi, bukan pada github.com standar.

Jika organisasi atau repositori yang diharapkan hilang, periksa akses akun GitHub dan otorisasi Aplikasi OAuth sebelum mengubah pengaturan organisasi Apidog.

Langkah 4: Impor file OpenAPI

Untuk mengimpor file OpenAPI atau Swagger dari repositori yang terhubung:

1. mulai alur kerja impor di proyek Apidog;
2. pilih OpenAPI/Swagger;
3. pilih Repositori Git;
4. pilih organisasi GitHub, repositori, cabang, dan file;
5. pilih Lanjutkan;
6. pilih Modul target yang sudah ada atau buat yang baru;
7. selesaikan impor;
8. tinjau titik akhir dan skema yang diimpor sebelum menerima hasilnya.

Pilih repositori, cabang, dan file spesifikasi yang diperlukan oleh proyek.

Gunakan proyek non-produksi untuk impor pertama, terutama jika modul target sudah berisi definisi API.

Langkah 5: Pilih alur kerja sinkronisasi berkelanjutan

Koneksi repositori dapat mendukung berbagai alur kerja. Pilih satu sumber kebenaran dan dokumentasikan untuk tim.

Jangan mengonfigurasi dua alur kerja otomatis yang berlawanan terhadap file yang sama tanpa aturan penyelesaian konflik yang jelas.

Untuk pencadangan:

1. buat atau pilih koneksi Git di pengaturan proyek;
2. buka Gambaran Umum > Spesifikasi API modul;
3. tambahkan atau pilih spesifikasi OpenAPI;
4. aktifkan Pencadangan ke Repositori Git;
5. pilih koneksi repositori, cabang, dan jalur file target;
6. simpan konfigurasi.

Untuk sumber kebenaran berbasis repositori, gunakan Impor Terjadwal atau tinjau Mode Spec-first.

Langkah 6: Verifikasi integrasi

Jalankan pengujian end-to-end kecil:

1. konfirmasi otorisasi membuka tenant GHE.com yang dikonfigurasi
2. konfirmasi hanya organisasi dan repositori yang diharapkan yang tersedia
3. impor file OpenAPI yang diketahui dan bandingkan hasilnya dengan sumber
4. uji arah pencadangan atau sinkronisasi yang dipilih dalam cabang sekali pakai
5. konfirmasi perlindungan cabang dan izin repositori berfungsi sesuai harapan
6. tinjau log atau kesalahan sinkronisasi
7. rotasi Client Secret Aplikasi OAuth dan konfirmasi proses pembaruan yang didokumentasikan berfungsi

Jika sinkronisasi webhook digunakan, verifikasi bahwa penginstal memiliki izin admin repositori dan bahwa peristiwa push yang diharapkan memicu sinkronisasi.

Perbarui atau hapus pengaturan organisasi

Administrator Organisasi dapat mengedit URL host atau Client ID dan dapat merotasi Client Secret dengan memasukkan nilai baru.

Untuk menghapus konfigurasi tingkat organisasi, buka Pengaturan Organisasi > Integrasi GitHub, temukan integrasi residensi data, dan pilih Hapus pengaturan.

Setelah pengaturan dihapus, pengguna tidak dapat membuat koneksi GitHub Enterprise Cloud baru hingga integrasi dikonfigurasi ulang. Koneksi yang ada mungkin memerlukan konfigurasi ulang atau otorisasi ulang tergantung pada status token dan pengaturan organisasi.

Pemecahan Masalah

Batas keamanan dan residensi data

• Hanya Administrator Organisasi yang dapat mengonfigurasi atau menghapus integrasi GHE.com.
• Client Secret tidak ditampilkan setelah konfigurasi.
• Izin proyek masih mengontrol siapa yang dapat membuat atau memperbarui koneksi Git.
• Otorisasi OAuth terjadi melalui tenant GHE.com yang dikonfigurasi.
• Izin OAuth yang diminta dapat mencakup akses yang diperlukan untuk membaca organisasi, repositori, cabang, mengimpor file, menulis cadangan, dan mengelola hook repositori saat diperlukan oleh alur kerja sinkronisasi.

Menghubungkan tenant residensi data tidak dengan sendirinya membuktikan bahwa setiap kategori data terkait GitHub atau Apidog tetap berada di satu wilayah. GitHub mendokumentasikan data yang dicakup oleh penawaran residensinya dan pengecualian yang relevan. Apidog adalah layanan terpisah yang terhubung dengan model penyimpanan dan penyebaran sendiri. Tinjau dokumentasi terkini dari kedua vendor sebagai bagian dari penilaian residensi data atau kepatuhan.

Tutorial tata kelola API terkait:

Tutorial ini mencakup kontrol pelengkap untuk mengatur ruang kerja API perusahaan:

• Kerangka Tata Kelola API — menghubungkan kepemilikan, kontrol, bukti, dan keputusan siklus hidup.
• Pemetaan Grup SAML dengan Microsoft Entra ID — menetapkan akses tim dari grup penyedia identitas.
• Pemindai Rahasia — meninjau kredensial yang mungkin terekspos dalam aset Apidog yang didukung.
• Log Audit — menyelidiki dan mengekspor aktivitas organisasi administratif.
• Penyediaan SCIM — mengelola pengguna organisasi melalui siklus hidup identitas.
• Kebijakan Perusahaan — mengonfigurasi kredensial, keanggotaan, sesi SSO, dan kontrol undangan.
• Tim API Layanan Mandiri yang Diatur — memungkinkan tim yang dibuat anggota sambil tetap mempertahankan pengawasan kepemilikan.
• Integrasi GitHub Enterprise Cloud — menghubungkan repositori GHE.com yang didukung untuk alur kerja OpenAPI.

Dokumentasi resmi terkait:

• Apidog GitHub Enterprise Cloud
• Koneksi Git
• Impor Terjadwal
• Mode Spec-first
• GitHub: Tentang residensi data
• GitHub: Penyimpanan data dengan residensi data