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.

Apidog'u bugün deneyin

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

Başlamadan Önce

Şunlara ihtiyacınız vardır:

• 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 GitHub Enterprise Cloud veri ikametli kiracı
• Bu kiracıda OAuth Uygulaması oluşturma izni
• Bağlanacak 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 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 şu şekilde ayarlayın: https://apidog.com/?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation
6. Yetkilendirme geri arama URL'sini şu şekilde 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 şekilde kopyalayın.

Geri arama URL'si, belgelenen Apidog URL'siyle tam olarak eşleşmelidir.

İstemci Gizli Anahtarını onaylanmış gizli anahtar yönetim sisteminizde saklayın. Bu anahtarı 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 bölümünü bulun ve Yapılandır'ı seçin.

1. https://company.ghe.com gibi GHE.com ana bilgisayar URL'sini girin.
2. Kimlik doğrulama yöntemi olarak OAuth Uygulaması'nı seçin.
3. OAuth Uygulaması İstemci Kimliğini girin.
4. OAuth Uygulaması İstemci Gizli Anahtarını girin.
5. 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.

Yapılandırmayı daha sonra düzenlerken İstemci Gizli Anahtarı alanını boş bırakırsanız mevcut gizli anahtar korunur. Yeni bir değer yalnızca anahtarı döndürürken girilmelidir.

Adım 3: Apidog Projesinden Depo Bağlayın

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

1. Gerekli Apidog projesini açın.
2. 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ında gerçekleştirilir.

Beklenen organizasyon veya depo görünmüyorsa Apidog organizasyon ayarlarını değiştirmeden önce GitHub hesabının erişimini ve OAuth Uygulaması yetkilendirmesini kontrol edin.

Adım 4: OpenAPI Dosyası İçe Aktarın

Bağlı depodan OpenAPI veya Swagger dosyası 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. İçe aktarmayı tamamlayın.
8. Sonucu kabul etmeden önce içe aktarılan uç noktaları ve şemaları gözden geçirin.

Projenin gerektirdiği depo, dal ve belirtim dosyasını seçin.

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

Adım 5: Sürekli Senkronizasyon İş Akışını Seçin

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

İş Akışı	Ne zaman kullanılır	Önemli davranış
Manuel İçe Aktarma	Değişiklikler Apidog'a yalnızca talep edildiğinde getirilir.	Her içe aktarmayı ve hedef modülü gözden geçirin.
Planlı İçe Aktarma	Git dosyası kaynak olarak kalır ve Apidog'un dosyayı belirli aralıklarla yenilemesi gerekir.	Yapılandırılmış yürütme moduna göre yerel istemci veya kendi kendine barındırılan Çalıştırıcı (Runner) aracılığıyla çalışır.
Git'e Yedekleme	Apidog içeriği bir depo dosyasına yazılmalıdır.	Depoyu, dalı ve hedef dosya yolunu yapılandırın. Otomatik yedeklemeler gece, rastgele planlanmış yoğun olmayan bir dönemde çalışır.
Önce Belirtim Modu (Spec-first Mode)	Belirtim dosyası doğruluk kaynağıdır ve ekip Git odaklı bir iş akışıyla düzenleme yapar.	Bu mod şu anda beta aşamasındadır. Webhook kurulumu genellikle depo yöneticisi izni gerektirir.

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

Yedeklemeyi Yapılandırma

1. Proje ayarlarında Git bağlantısını oluşturun veya seçin.
2. Modül > 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:

• Yetkilendirmenin yapılandırılmış GHE.com kiracısını açtığını doğrulayın.
• Yalnızca beklenen organizasyonların ve depoların kullanılabildiğini doğrulayın.
• Bilinen bir OpenAPI dosyasını içe aktarın ve sonucu kaynakla karşılaştırın.
• Seçilen yedekleme veya senkronizasyon yönünü tek kullanımlık bir dalda test edin.
• Dal korumasının ve depo izinlerinin beklendiği gibi çalıştığını doğrulayın.
• Senkronizasyon günlüklerini ve hatalarını gözden geçirin.
• OAuth Uygulaması İstemci Gizli Anahtarını döndürün ve belgelenen güncelleme sürecini test edin.

Webhook senkronizasyonu kullanıyorsanız yükleyicinin depo yöneticisi 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. İstemci Gizli Anahtarını döndürmek için yeni bir değer girilmelidir.

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 kullanıcılar entegrasyon yeniden yapılandırılana kadar yeni GitHub Enterprise Cloud bağlantıları oluşturamaz. Mevcut bağlantılar token durumuna ve organizasyon ayarlarına bağlı olarak yeniden yapılandırma veya yeniden yetkilendirme gerektirebilir.

Sorun Giderme

Sorun	Ne kontrol edilmeli
Entegrasyon seçeneği kullanılamıyor	Kuruluşun Enterprise özelliğine erişimi olduğunu ve sizin Organizasyon Yöneticisi olduğunuzu doğrulayın.
OAuth geri arama hatası döndürüyor	OAuth Uygulaması geri aramasının tam olarak https://api.apidog.com/passport/github/callback olduğunu doğrulayın.
Yetkilendirme github.com'u açıyor	Organizasyon düzeyindeki ana bilgisayarın amaçlanan kök *.ghe.com kiracısı olduğunu doğrulayın.
Bir depo eksik	Yetkili GitHub kullanıcısının organizasyon ve depo erişimini ve OAuth kısıtlamalarını kontrol edin.
Proje kullanıcısı bağlantı oluşturamıyor	Kullanıcının gerekli proje düzeyinde Git bağlantı iznine sahip olduğunu doğrulayın.
İçe aktarma veya senkronizasyon başarısız oluyor	Seçilen dalı, dosya yolunu, dosya biçimini, depo izinlerini ve senkronizasyon günlüklerini kontrol edin.

Güvenlik ve Veri İkameti 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, Git bağlantılarını kimlerin oluşturabileceğini veya güncelleyebileceğini kontrol etmeye devam eder.
• OAuth yetkilendirmesi yapılandırılmış GHE.com kiracısı üzerinden gerçekleşir.
• İstenen OAuth izinleri, senkronizasyon iş akışının gerektirdiği şekilde organizasyonları, depoları ve dalları okumak; dosyaları içe aktarmak; yedekleri yazmak ve depo kancalarını yönetmek için gereken erişimi içerebilir.

Veri ikametli bir kiracıyı bağlamak, GitHub veya Apidog ile ilgili her tür verinin tek bir bölgede kaldığını tek başına kanıtlamaz. GitHub, ikamet teklifi ve ilgili istisnalar tarafından kapsanan verileri belgeler. Apidog ise kendi depolama ve dağıtım modeline sahip ayrı bir bağlı hizmettir. Veri ikameti veya uyumluluk değerlendirmesi kapsamında her iki sağlayıcının güncel belgelerini inceleyin.

İlgili API Yönetişimi Eğitimleri

Bu eğitimler, 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 — yönetimsel organizasyon etkinliğini araştırın ve dışa aktarın.
• SCIM Sağlama — organizasyon kullanıcılarını kimlik yaşam döngüsü üzerinden 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