Walse

Posted on Aug 31 Originally published at apidog.com

Cara Menghubungkan Repositori GHE.com ke Apidog

Menghubungkan Apidog ke GitHub Enterprise Cloud dengan Residensi Data

Apidog dapat terhubung ke tenant residensi data GitHub Enterprise Cloud yang di-hosting pada domain khusus *.ghe.com. Setelah Administrator Organisasi mengonfigurasi tenant dan Aplikasi OAuth, pengguna proyek yang berwenang dapat menghubungkan repositori untuk mengimpor, mencadangkan, dan menyinkronkan spesifikasi OpenAPI.

Coba Apidog hari ini

Integrasi ini hanya mendukung tenant SaaS residensi data GitHub Enterprise Cloud. GitHub Enterprise Server dan domain GitHub khusus lainnya tidak didukung.

Sebelum memulai

Pastikan Anda memiliki:

organisasi Apidog Enterprise dengan akses integrasi;
izin Administrator Organisasi di Apidog;
tenant residensi data GitHub Enterprise Cloud pada domain root *.ghe.com, misalnya https://company.ghe.com;
izin membuat Aplikasi OAuth pada tenant tersebut;
akses ke organisasi, repositori, dan cabang GitHub yang akan dihubungkan.

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

Langkah 1: Buat Aplikasi OAuth di tenant GHE.com

Masuk ke tenant GHE.com organisasi Anda.
Buka pengaturan Aplikasi OAuth.
Buat Aplikasi OAuth baru dengan nama yang mudah diidentifikasi.
Atur URL beranda ke https://apidog.com.
Atur URL callback otorisasi ke https://api.apidog.com/passport/github/callback.
Daftarkan Aplikasi OAuth.
Salin Client ID.
Buat dan salin Client Secret dengan aman.

URL callback harus sama persis dengan URL Apidog yang didokumentasikan.

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

Langkah 2: Konfigurasikan tenant GHE.com di Apidog

Hanya Administrator Organisasi yang dapat mengonfigurasi atau menghapus integrasi ini.

Buka organisasi Apidog.
Buka Pengaturan Organisasi > Integrasi GitHub.
Temukan Residensi Data GitHub Enterprise Cloud, lalu pilih Konfigurasi.

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

Konfigurasikan host tenant dan kredensial Aplikasi OAuth di tingkat organisasi.

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

Saat mengedit konfigurasi:

biarkan kolom Client Secret kosong untuk mempertahankan rahasia yang ada;
masukkan nilai baru hanya ketika merotasi Client Secret.

Langkah 3: Hubungkan repositori dari proyek Apidog

Setelah konfigurasi organisasi selesai:

Buka proyek Apidog.
Mulai koneksi Git atau alur kerja impor Git.
Pilih GitHub Enterprise Cloud.
Lanjutkan ke halaman otorisasi pada tenant GHE.com yang dikonfigurasi.
Masuk dan otorisasi Aplikasi OAuth.
Pilih organisasi GitHub, repositori, dan cabang.
Selesaikan koneksi.

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

Jika organisasi atau repositori tidak muncul, 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:

Mulai alur kerja impor di proyek Apidog.
Pilih OpenAPI/Swagger.
Pilih Repositori Git.
Pilih organisasi GitHub, repositori, cabang, dan file.
Pilih Lanjutkan.
Pilih Modul target yang sudah ada atau buat modul baru.
Selesaikan impor.
Tinjau endpoint dan skema yang diimpor sebelum menerima hasilnya.

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

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

Langkah 5: Pilih alur kerja sinkronisasi

Koneksi repositori dapat mendukung beberapa alur kerja. Tetapkan satu sumber kebenaran dan dokumentasikan aturan penggunaannya untuk tim.

Alur kerja	Gunakan saat	Perilaku penting
Impor Manual	Perubahan hanya dibawa ke Apidog saat diminta	Tinjau setiap impor dan Modul target
Impor Terjadwal	File Git tetap menjadi sumber kebenaran dan Apidog perlu diperbarui berkala	Berjalan melalui klien lokal atau Runner yang di-hosting sendiri, sesuai mode eksekusi
Pencadangan ke Git	Konten Apidog harus ditulis ke file repositori	Tentukan repositori, cabang, dan jalur file target; pencadangan otomatis berjalan pada periode non-puncak malam hari yang dijadwalkan secara acak
Mode Spec-first	File spesifikasi adalah sumber kebenaran dan tim mengedit melalui alur kerja berbasis Git	Saat ini masih beta; pemasangan webhook biasanya memerlukan izin admin repositori

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

Mengaktifkan pencadangan ke Git

Buat atau pilih koneksi Git di pengaturan proyek.
Buka Gambaran Umum > Spesifikasi API pada modul.
Tambahkan atau pilih spesifikasi OpenAPI.
Aktifkan Pencadangan ke Repositori Git.
Pilih koneksi repositori, cabang, dan jalur file target.
Simpan konfigurasi.

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

Langkah 6: Verifikasi integrasi

Lakukan pengujian end-to-end kecil:

pastikan otorisasi membuka tenant GHE.com yang dikonfigurasi;
pastikan hanya organisasi dan repositori yang diharapkan yang tersedia;
impor file OpenAPI yang dikenal, lalu bandingkan hasilnya dengan sumber;
uji arah pencadangan atau sinkronisasi pada cabang sekali pakai;
pastikan perlindungan cabang dan izin repositori berfungsi sesuai harapan;
tinjau log serta kesalahan sinkronisasi;
rotasi Client Secret dan pastikan prosedur pembaruannya berhasil.

Jika menggunakan sinkronisasi webhook, pastikan penginstal memiliki izin admin repositori dan peristiwa push yang diharapkan memicu sinkronisasi.

Perbarui atau hapus pengaturan organisasi

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

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

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

Pemecahan masalah

Masalah	Yang harus diperiksa
Opsi integrasi tidak tersedia	Pastikan organisasi memiliki akses fitur Enterprise dan Anda adalah Administrator Organisasi.
OAuth mengembalikan kesalahan callback	Pastikan callback Aplikasi OAuth sama persis dengan `https://api.apidog.com/passport/github/callback`.
Otorisasi membuka `github.com`	Pastikan host tingkat organisasi adalah tenant root `*.ghe.com` yang benar.
Repositori hilang	Periksa akses pengguna ke organisasi dan repositori serta pembatasan OAuth.
Pengguna proyek tidak dapat membuat koneksi	Pastikan pengguna memiliki izin koneksi Git tingkat proyek yang diperlukan.
Impor atau sinkronisasi gagal	Periksa cabang, jalur file, format file, izin repositori, dan log sinkronisasi.

Batas keamanan dan residensi data

Hanya Administrator Organisasi yang dapat mengonfigurasi atau menghapus integrasi GHE.com.
Client Secret tidak ditampilkan setelah konfigurasi.
Izin proyek tetap mengontrol siapa yang dapat membuat atau memperbarui koneksi Git.
Otorisasi OAuth berlangsung melalui tenant GHE.com yang dikonfigurasi.
Izin OAuth dapat mencakup akses untuk membaca organisasi, repositori, dan cabang; mengimpor file; menulis cadangan; serta mengelola hook repositori jika diperlukan oleh alur 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 tercakup dan pengecualian dalam penawaran residensinya. Apidog adalah layanan terpisah dengan model penyimpanan dan penyebaran sendiri. Tinjau dokumentasi terbaru dari kedua vendor sebagai bagian dari penilaian residensi data atau kepatuhan.

Tutorial tata kelola API terkait

Tutorial berikut 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 berdasarkan grup penyedia identitas.
Pemindai Rahasia — meninjau kredensial yang mungkin terekspos dalam aset Apidog.
Log Audit — menyelidiki dan mengekspor aktivitas administratif organisasi.
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 pembuatan tim oleh anggota dengan pengawasan kepemilikan.
Integrasi GitHub Enterprise Cloud — menghubungkan repositori GHE.com yang didukung untuk alur kerja OpenAPI.

DEV Community