GHE.com Deposunu Apidog'a Nasıl Bağlanır

Apidog, özel *.ghe.com alan adlarında barındırılan GitHub Enterprise Cloud veri ikametli (data-residency) kiracılarına bağlanabilir. Bir Organizasyon Yöneticisi kiracıyı ve OAuth Uygulamasını yapılandırdıktan sonra, yetkili proje kullanıcıları depoları bağlayabilir ve desteklenen OpenAPI içe aktarma, yedekleme ve senkronizasyon iş akışlarını kullanabilir.

Bu entegrasyon, GitHub Enterprise Cloud veri ikametli SaaS kiracıları içindir. GitHub Enterprise Server'ı veya rastgele özel GitHub alan adlarını desteklemez.

Başlamadan Önce

İhtiyaçlarınız:

• Entegrasyona erişimi olan bir Apidog Enterprise kuruluşu
• Apidog'da Organizasyon Yöneticisi izni
• https://company.ghe.com gibi bir kök *.ghe.com alan adında bir GitHub Enterprise Cloud veri ikametli kiracı
• Bu kiracı üzerinde bir OAuth Uygulaması oluşturma izni
• Bağlamayı planladığınız GitHub organizasyonlarına, depolara ve dallara erişim

Depoları bağlayan kullanıcıların Apidog'da ilgili proje düzeyinde Git bağlantı iznine de sahip olması gerekir.

Adım 1: GHE.com kiracısında bir OAuth Uygulaması Oluşturun

1. Kuruluşunuzun GHE.com kiracısında oturum açın.
2. OAuth Uygulamaları ayarlarına gidin.
3. Yeni bir OAuth Uygulaması oluşturun.
4. Tanımlanabilir bir uygulama adı girin.
5. Ana sayfa URL'sini şuna ayarlayın:https://apidog.com
6. Yetkilendirme geri arama URL'sini şuna ayarlayın:https://api.apidog.com/passport/github/callback
7. OAuth Uygulamasını kaydedin.
8. İstemci Kimliğini (Client ID) kopyalayın.
9. İstemci Gizli Anahtarını (Client Secret) oluşturun ve güvenli bir şekilde kopyalayın.

Geri arama URL'si, belgelenmiş Apidog URL'si ile tam olarak eşleşmelidir.

İstemci Gizli Anahtarını onaylanmış gizli anahtar yönetim sisteminizde saklayın. Bir ekran görüntüsüne, bilete veya paylaşılan bir belgeye koymayın.

Adım 2: Apidog'da GHE.com kiracısını yapılandırın

Bu entegrasyonu yalnızca bir Organizasyon Yöneticisi yapılandırabilir veya temizleyebilir.

1. Apidog kuruluşunu açın.
2. Organizasyon Ayarları'na gidin.
3. GitHub Entegrasyonu'nu açın.
4. GitHub Enterprise Cloud Data Residency'yi bulun ve Yapılandır'ı seçin.

• https://company.ghe.com gibi GHE.com ana bilgisayar URL'sini girin.
• Kimlik doğrulama yöntemi olarak OAuth Uygulaması'nı seçin.
• OAuth Uygulaması İstemci Kimliğini girin.
• OAuth Uygulaması İstemci Gizli Anahtarını girin.
• Yapılandırmayı kaydedin.

Kiracı ana bilgisayarını ve OAuth Uygulaması kimlik bilgilerini organizasyon düzeyinde yapılandırın.

Kaydettikten sonra Apidog, yapılandırılmış ana bilgisayar URL'sini görüntüler. İstemci Gizli Anahtarı gösterilmez veya tekrar önceden doldurulmaz.

Daha sonra yapılandırmayı düzenlerken, İstemci Gizli Anahtarı alanını boş bırakmak mevcut gizli anahtarı korur. Yeni bir değer yalnızca döndürülürken girilmelidir.

Adım 3: Bir Apidog projesinden bir depo bağlayın

Organizasyon düzeyinde yapılandırma tamamlandıktan sonra:

1. gerekli Apidog projesini açın;
2. bir Git bağlantısı veya Git içe aktarma iş akışı başlatın;
3. GitHub Enterprise Cloud'u seçin;
4. yapılandırılmış GHE.com kiracısındaki yetkilendirme sayfasına devam edin;
5. oturum açın ve OAuth Uygulamasını yetkilendirin;
6. GitHub organizasyonunu seçin;
7. depoyu ve dalı seçin;
8. bağlantıyı tamamlayın.

Yetkilendirme, standart github.com üzerinde değil, yapılandırılmış GHE.com kiracısı üzerinde gerçekleştirilir.

Beklenen organizasyon veya depo eksikse, Apidog organizasyon ayarlarını değiştirmeden önce GitHub hesabının erişimini ve OAuth Uygulaması yetkilendirmesini kontrol edin.

Adım 4: Bir OpenAPI dosyası içe aktarın

Bağlı depodan bir OpenAPI veya Swagger dosyasını içe aktarmak için:

1. Apidog projesinde bir içe aktarma iş akışı başlatın;
2. OpenAPI/Swagger'ı seçin;
3. Git Deposu'nu seçin;
4. GitHub organizasyonunu, depoyu, dalı ve dosyayı seçin;
5. Devam et'i seçin;
6. mevcut bir hedef Modülü seçin veya yeni bir tane oluşturun;
7. içe aktarmayı tamamlayın;
8. sonucu kabul etmeden önce içe aktarılan uç noktaları ve şemaları gözden geçirin.

Proje tarafından gerekli depo, dal ve belirtim dosyasını seçin.

Özellikle hedef modül zaten API tanımları içeriyorsa, ilk içe aktarma için üretim dışı bir proje kullanın.

Adım 5: Devam eden senkronizasyon iş akışını seçin

Depo bağlantısı farklı iş akışlarını destekleyebilir. Tek bir doğruluk kaynağı seçin ve ekip için belgeleyin.

Açık bir çakışma çözümleme kuralı olmaksızın aynı dosya üzerinde birbirine zıt iki otomatik iş akışını yapılandırmayın.

Yedekleme için:

1. proje ayarlarında Git bağlantısını oluşturun veya seçin;
2. modülün Genel Bakış > API Belirtimi'ni açın;
3. OpenAPI belirtimini ekleyin veya seçin;
4. Git Deposuna Yedekle'yi etkinleştirin;
5. depo bağlantısını, dalı ve hedef dosya yolunu seçin;
6. yapılandırmayı kaydedin.

Depo güdümlü bir doğruluk kaynağı için Planlı İçe Aktarma'yı kullanın veya Önce Belirtim Modu'nu inceleyin.

Adım 6: Entegrasyonu Doğrulayın

Küçük bir uçtan uca test çalıştırın:

1. yetkilendirmenin yapılandırılmış GHE.com kiracısını açtığını onaylayın
2. yalnızca beklenen organizasyonların ve depoların kullanılabilir olduğunu onaylayın
3. bilinen bir OpenAPI dosyasını içe aktarın ve sonucu kaynakla karşılaştırın
4. seçilen yedekleme veya senkronizasyon yönünü tek kullanımlık bir dalda test edin
5. dal korumasının ve depo izinlerinin beklendiği gibi çalıştığını onaylayın
6. senkronizasyon günlüklerini veya hatalarını gözden geçirin
7. OAuth Uygulaması İstemci Gizli Anahtarını döndürün ve belgelenmiş güncelleme sürecinin çalıştığını onaylayın

Webhook senkronizasyonu kullanılıyorsa, yükleyicinin depo yönetici iznine sahip olduğunu ve beklenen push olayının senkronizasyonu tetiklediğini doğrulayın.

Organizasyon ayarlarını güncelleme veya temizleme

Organizasyon Yöneticileri, ana bilgisayar URL'sini veya İstemci Kimliğini düzenleyebilir ve yeni bir değer girerek İstemci Gizli Anahtarını döndürebilir.

Organizasyon düzeyindeki yapılandırmayı kaldırmak için Organizasyon Ayarları > GitHub Entegrasyonu'nu açın, veri ikametli entegrasyonu bulun ve Ayarları temizle'yi seçin.

Ayarlar temizlendikten sonra, entegrasyon tekrar yapılandırılana kadar kullanıcılar yeni GitHub Enterprise Cloud bağlantıları oluşturamaz. Mevcut bağlantılar, token durumu ve organizasyon ayarlarına bağlı olarak yeniden yapılandırma veya yeniden yetkilendirme gerektirebilir.

Sorun Giderme

Güvenlik ve veri ikameti sınırları

• Yalnızca Organizasyon Yöneticileri GHE.com entegrasyonunu yapılandırabilir veya temizleyebilir.
• İstemci Gizli Anahtarı yapılandırmadan sonra gösterilmez.
• Proje izinleri hala Git bağlantılarını kimlerin oluşturabileceğini veya güncelleyebileceğini kontrol eder.
• OAuth yetkilendirmesi, yapılandırılmış GHE.com kiracısı aracılığıyla gerçekleşir.
• Talep edilen OAuth izinleri, bir senkronizasyon iş akışı tarafından gerektiğinde organizasyonları, depoları, dalları okumak, dosyaları içe aktarmak, yedekleri yazmak ve depo kancalarını yönetmek için gereken erişimi içerebilir.

Bir veri ikametli kiracının bağlanması, GitHub veya Apidog ile ilgili her tür verinin tek bir bölgede kaldığını kendi başına kanıtlamaz. GitHub, ikamet teklifi ve ilgili istisnalar tarafından kapsanan verileri belgeler. Apidog, kendi depolama ve dağıtım modeline sahip ayrı bir bağlı hizmettir. Veri ikameti veya uyumluluk değerlendirmesinin bir parçası olarak her iki sağlayıcının güncel belgelerini gözden geçirin.

İlgili API yönetişimi eğitimleri:

Bu eğitimler, bir kurumsal API çalışma alanını yönetmek için tamamlayıcı kontrolleri kapsar:

• API Yönetişim Çerçevesi — sahipliği, kontrolleri, kanıtları ve yaşam döngüsü kararlarını birbirine bağlayın.
• Microsoft Entra ID ile SAML Grup Eşleme — kimlik sağlayıcı gruplarından ekip erişimi atayın.
• Gizli Anahtar Tarayıcı (Secret Scanner) — desteklenen Apidog varlıklarındaki olası açığa çıkan kimlik bilgilerini gözden geçirin.
• Denetim Günlükleri — idari organizasyon etkinliğini araştırın ve dışa aktarın.
• SCIM Sağlama — kimlik yaşam döngüsü aracılığıyla organizasyon kullanıcılarını yönetin.
• Kurumsal Politikalar — kimlik bilgisi, üyelik, SSO oturumu ve davetiye kontrollerini yapılandırın.
• Yönetilen Self-Servis API Ekipleri — sahiplik denetimini korurken üyeler tarafından oluşturulan ekiplere izin verin.
• GitHub Enterprise Cloud Entegrasyonu — OpenAPI iş akışları için desteklenen GHE.com depolarını bağlayın.

İlgili resmi belgeler:

• Apidog GitHub Enterprise Cloud
• Git Bağlantısı
• Planlı İçe Aktarma
• Önce Belirtim Modu
• GitHub: Veri ikameti hakkında
• GitHub: Veri ikameti ile verilerinizin depolanması hakkında