Apidog GitHub ve GitLab'e Nasıl Bağlanır

API belirtimleriniz Apidog'da, doğruluk kaynağınız ise Git'te duruyorsa ikisini aynı hizada tutmanız gerekir. Apidog Git entegrasyonu; GitHub, GitLab veya Azure DevOps deposunu Apidog projenize bağlamanızı, OpenAPI belirtimlerini Git'e push etmenizi ve depo değişikliklerini Apidog'a geri çekmenizi sağlar. Sonuç: denetlenebilir değişiklik geçmişi, pull request üzerinden belirtim incelemesi ve Apidog dışına alınmış sürümlü bir yedek.

Apidog'u bugün deneyin

Bu rehber, Apidog Git entegrasyonunu uygulama odaklı ele alır: hangi sağlayıcıyı nasıl bağlayacağınız, iki yönlü senkronizasyon ile otomatik yedekleme arasındaki fark, dal/depo yapısı, izinler ve sorun giderme. Yalnızca GitHub akışına odaklanmak istiyorsanız OpenAPI belirtiminizi GitHub ile nasıl senkronize edeceğinize dair rehberi okuyabilirsiniz.

Apidog Git entegrasyonu ne işe yarar?

Apidog Git ile iki ayrı şekilde çalışır. Bunları karıştırmamak önemlidir:

1. Belirtim-Önce Modu ile iki yönlü senkronizasyon

   • Apidog içinde OpenAPI YAML/JSON düzenlersiniz.
   • Değişiklikleri commit edip bağlı Git dalına push edersiniz.
   • Depoda yapılan değişiklikleri Apidog'a pull edersiniz.

2. Otomatik Git yedeklemesi

   • Apidog, modüllerin OpenAPI/Swagger dosyalarını belirlediğiniz Git deposuna zamanlanmış olarak push eder.
   • Tek yönlüdür: Apidog → Git.
   • Düzenleme akışı değil, sürümlü yedekleme mekanizmasıdır.

Yetenek	Yön	Tetikleyici	En uygun kullanım
Belirtim-Önce Modu senkronizasyonu	İki yönlü: push ve pull	Manuel commit/push, manuel pull	OpenAPI belirtimini kod gibi yöneten ekipler
Otomatik Git yedeklemesi	Tek yönlü: Apidog → Git	Zamanlanmış, yoğun olmayan saatler	İş akışını değiştirmeden sürümlü yedek isteyen ekipler

Bu yazıda senkronizasyon dediğimizde Belirtim-Önce Modu'ndaki iki yönlü akışı, yedekleme dediğimizde ise zamanlanmış tek yönlü dışa aktarımı kastediyoruz.

Desteklenen Git sağlayıcıları

Apidog; GitHub, GitLab ve Azure DevOps ile çalışır.

Sağlayıcı	Kimlik doğrulama yöntemi	Notlar
GitHub	OAuth yetkilendirmesi	Kişisel ve organizasyon depolarıyla çalışır. Organizasyon depoları için yönetici onayı gerekebilir.
GitLab	OAuth yetkilendirmesi	gitlab.com ve Apidog tarafından erişilebilen self-managed GitLab örnekleri desteklenir.
Azure DevOps	Genel Git Bağlantısı: HTTPS + token	HTTPS repo URL'si ve depo kapsamına sahip kişisel erişim belirteci kullanılır.

Genel Git Bağlantısı yalnızca Azure DevOps için değildir. Git sunucunuz HTTPS klonlama URL'si ve token tabanlı kimlik doğrulama destekliyorsa, aynı akış self-hosted Git kurulumları için de kullanılabilir.

Git sağlayıcınızı bağlama

Bağlantı adımı üç karardan oluşur:

1. Sağlayıcıyı yetkilendirirsiniz.
2. Depoyu seçersiniz.
3. Senkronize edilecek dalı seçersiniz.

GitHub bağlama

GitHub için Apidog, OAuth akışını kullanır.

Uygulama adımları:

1. Apidog projenizde Git entegrasyonu ayarlarına gidin.
2. GitHub sağlayıcısını seçin.
3. GitHub OAuth ekranında Apidog'a gerekli depo erişimini verin.
4. Depo bir organizasyona aitse, gerekirse organizasyon yöneticisinden üçüncü taraf uygulama erişimini onaylamasını isteyin.
5. Depoyu ve hedef dalı seçin.

Organizasyon deposu görünmüyorsa genellikle sorun yetki değil, eksik organizasyon onayıdır.

GitLab bağlama

GitLab akışı GitHub'a benzerdir:

1. GitLab sağlayıcısını seçin.
2. GitLab OAuth ekranında oturum açın.
3. Depo erişimini onaylayın.
4. Depo ve dal seçimini yapın.

Self-managed GitLab kullanıyorsanız Apidog'un GitLab örneğinize ağ üzerinden erişebildiğinden emin olun.

Azure DevOps bağlama

Azure DevOps için Genel Git Bağlantısı kullanılır.

Gerekenler:

• Deponun HTTPS klonlama URL'si
• Kod okuma/yazma iznine sahip kişisel erişim belirteci, yani PAT

Uygulama adımları:

1. Azure DevOps'ta hedef proje için PAT oluşturun.
2. PAT kapsamını yalnızca gerekli kod okuma/yazma izinleriyle sınırlayın.
3. Apidog'da Genel Git Bağlantısı seçeneğini açın.
4. HTTPS repo URL'sini ve PAT değerini girin.
5. Depo/dal eşlemesini tamamlayın.

PAT, Apidog'un Git'e commit push edebilmesini sağlayan kimlik bilgisidir. Bu nedenle tam hesap erişimi veren geniş kapsamlı token kullanmayın.

İzinleri doğru ayarlama

Kurulumdan önce şu kontrolleri yapın:

• Organizasyon depoları: GitHub/GitLab organizasyonlarında üçüncü taraf uygulama erişimi yönetici onayı gerektirebilir.
• PAT kapsamı: Azure DevOps ve genel bağlantılarda token'ı yalnızca hedef depo veya proje için yetkilendirin.
• Özel depolar: Özel depolar desteklenir. Erişim, verdiğiniz OAuth yetkisi veya token üzerinden sağlanır.
• Dal seçimi: Başlangıç için genellikle main kullanılır; inceleme gerektiren değişikliklerde feature branch tercih edin.

OpenAPI belirtimlerini Git ile yönetme pratiklerini daha geniş ele almak için Git ile OpenAPI sürüm kontrolü rehberine bakabilirsiniz.

Belirtim-Önce Modu ile iki yönlü senkronizasyon

Belirtim-Önce Modu, Apidog'u Git'e commit atabilen bir OpenAPI düzenleyicisine dönüştürür. Resmi referans için Apidog dokümantasyonundaki Spec-First Mode sayfasını inceleyebilirsiniz.

Pratik akış şu şekildedir:

1. OpenAPI belgesini Apidog'da YAML veya JSON olarak düzenlersiniz.
2. Apidog canlı doğrulama, sözdizimi vurgulama ve otomatik tamamlama ile hataları yazarken gösterir.
3. Değişiklikleri commit mesajıyla kaydedersiniz.
4. Bağlı Git dalına push edersiniz.
5. Depoda başkası değişiklik yaptıysa Apidog'a pull edersiniz.

Örnek bir OpenAPI değişikliği:

paths:
  /v1/orders/{orderId}:
    get:
      operationId: getOrder
      summary: Retrieve a single order
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The requested order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'

Bu değişiklikten sonra önerilen çalışma sırası:

1. Depodaki son değişiklikleri Apidog'a pull et
2. OpenAPI belirtimini düzenle
3. Canlı doğrulama hatalarını düzelt
4. Commit mesajı yaz
5. Bağlı dala push et
6. Gerekirse pull request aç

Push tamamlandığında senkronizasyon göstergesi Apidog ile Git dalının aynı içerikte olduğunu belirtir.

Eğer deneme amaçlı düzenlemeleri saklamak istemiyorsanız commit etmeden önce push edilmemiş düzenlemeleri atabilirsiniz. Bu işlem çalışma kopyasını son senkronize edilmiş duruma döndürür.

Bu ritim, Git-yerel API iş akışının temelidir: API belirtimi de kod gibi review, geçmiş ve rollback süreçlerinden geçer.

Otomatik Git yedeklemesi

Otomatik yedekleme, günlük düzenleme akışınızı değiştirmeden OpenAPI belirtimlerini Git'te sürümlendirmenizi sağlar.

Akış:

1. Apidog'da bir modülü seçersiniz.
2. Hedef Git deposunu ve dalı yapılandırırsınız.
3. Apidog, modülün OpenAPI/Swagger dosyasını dışa aktarır.
4. Sistem bunu zamanlanmış olarak Git'e push eder.
5. Her push Git'te commit geçmişi oluşturur.

Bu mekanizma şu durumlar için uygundur:

• API belirtimlerinin Git'te yedeklenmesini istiyorsanız
• Değişiklik geçmişini Git üzerinden görmek istiyorsanız
• Ekip henüz spec-first çalışma modeline geçmediyse
• Manuel commit/push süreci istemiyorsanız

Yedekleme tek yönlüdür. Depodaki değişiklikler Apidog'a geri okunmaz. Depodaki düzenlemelerin Apidog'a dönmesini istiyorsanız Belirtim-Önce Modu kullanmalısınız.

Dal ve depo yapısını seçme

Git entegrasyonunu kurmadan önce iki yapısal karar verin:

• Hangi dal kullanılacak?
• Tek depo mu, çoklu depo mu kullanılacak?

Dal seçimi

Genel öneri:

• main: Onaylanmış ve standart API belirtimi
• Feature branch: Devam eden API tasarımları
• Pull request: Belirtim değişikliklerini incelemek için

Örnek akış:

feature/add-order-endpoint
        ↓
Pull request
        ↓
Review
        ↓
main

Apidog'u doğrudan main dalına bağlamak daha basittir, ancak review kapısını atlar. Küçük ekiplerde veya düşük riskli değişikliklerde yeterli olabilir. Daha kontrollü ekiplerde feature branch + PR modeli daha güvenlidir.

Tek depo mu, çok depo mu?

Yapı	Ne zaman uygun?	Dikkat edilmesi gerekenler
Her API için ayrı depo	API sahipliği ekipler arasında bölünmüşse	Erişim kontrolü daha net olur
Tüm API'ler için monorepo	Platform ekibi tüm API yüzeyini yönetiyorsa	Dizin yapısı tutarlı olmalı

Monorepo kullanıyorsanız her modüle ayrı klasör verin:

api-specs/
  billing/
    openapi.yaml
  orders/
    openapi.yaml
  users/
    openapi.yaml

Bu yapı, yedekleme ve senkronizasyonların çakışmasını önler; pull request incelemelerinde farkları okumayı kolaylaştırır.

Ekip izinleri ve erişim

Git entegrasyonunda izinler iki yerde yönetilir:

1. Apidog içindeki proje/ekip izinleri
2. Git sağlayıcısındaki repo/token izinleri

Apidog tarafında:

• Push yetkisini yalnızca belirtim sahiplerine verin.
• Diğer ekip üyelerine gerektiğinde okuma veya inceleme erişimi tanımlayın.
• Yanlışlıkla yapılan push'ları önlemek için yazma erişimini sınırlayın.

Git sağlayıcısı tarafında:

• GitHub/GitLab OAuth yetkisi, yetkilendiren kullanıcının erişimini taşır.
• Azure DevOps PAT bir sırdır; paylaşılan dokümanlara eklemeyin.
• Token kapsamını hedef repo/proje ile sınırlandırın.
• Ekipten ayrılan kullanıcıların token'larını iptal edin.
• Gerekirse entegrasyonu aktif bir servis hesabı veya sahip hesabı üzerinden yeniden yetkilendirin.

Temel ilke: entegrasyon, arkasındaki en zayıf kimlik bilgisi kadar güvenlidir.

Birleştirme çakışmalarını ve sürüklenmeyi yönetme

Apidog gerçek Git geçmişiyle çalıştığı için Git'in normal çakışma modelini kullanır. İki kişi aynı OpenAPI satırlarını değiştirdiğinde merge conflict oluşabilir.

Örnek senaryo:

1. Siz Apidog'da Order şemasını değiştirirsiniz.
2. Ekip arkadaşınız aynı şemayı depoda değiştirip önce push eder.
3. Siz push veya pull yaptığınızda Git çakışma üretir.
4. Çakışmayı YAML üzerinde çözmeniz gerekir.

Çakışma riskini azaltmak için:

Her düzenlemeden önce pull yap
Küçük ve odaklı değişiklikler yap
Aynı şema üzerinde paralel çalışmayı azalt
Feature branch kullan
Pull request ile inceleme yap

Çakışma oluşursa:

1. YAML conflict işaretlerini bulun.
2. Doğru alanları koruyun.
3. OpenAPI yapısının geçerli kaldığını kontrol edin.
4. Apidog canlı doğrulama hatalarını düzeltin.
5. Yeniden senkronize edin.

Sürüklenme, yani Apidog ile Git deposunun sessizce ayrışması, genellikle push edilmemiş veya pull edilmemiş değişikliklerden kaynaklanır. Senkronizasyon göstergesi "Şimdi senkronize edildi" durumunda değilse önce bekleyen değişiklikleri uzlaştırın.

Sorun giderme

Belirti	Olası neden	Çözüm
Yetkilendirme başarısız oluyor veya depo görünmüyor	Organizasyon üçüncü taraf erişimini onaylamadı ya da token kapsamı eksik	GitHub/GitLab için organizasyon yöneticisinden onay alın; Azure DevOps için PAT'yi okuma/yazma kod kapsamıyla yeniden oluşturun
Push reddedildi	Token iptal edildi, süresi doldu veya yazma izni yok	Sağlayıcıyı yeniden yetkilendirin; genel bağlantılarda yeni PAT oluşturup Apidog'da güncelleyin
Değişiklikler push edildi ama beklenen yerde görünmüyor	Yanlış dala push edildi	Apidog proje ayarlarında bağlı dalı kontrol edin
Senkronizasyon takılı kaldı	Push edilmemiş yerel düzenlemeler veya pull gereksinimi var	Önce pull yapın, sonra bekleyen değişiklikleri commit edip push edin
OpenAPI belirtiminde merge conflict oluştu	Aynı satırlarda paralel düzenleme yapıldı	YAML çakışmasını çözün, belgeyi geçerli tutun ve yeniden senkronize edin
Yedekleme çalışmadı	Zamanlanmış yoğun olmayan pencere henüz gelmedi veya yapılandırma hatalı	Bir sonraki döngüyü bekleyin; depo/dal yapılandırmasını doğrulayın
Saklamak istemediğiniz düzenlemeler var	Commit öncesi deneysel değişiklikler	Push edilmemiş düzenlemeleri atarak son senkronize duruma dönün

Tekrarlayan sorunlarda ilk kontrol etmeniz gerekenler:

Token hâlâ aktif mi?
Token doğru kapsamda mı?
Doğru depo seçildi mi?
Doğru dal seçildi mi?
Organizasyon uygulama erişimini onayladı mı?

Sıkça Sorulan Sorular

Senkronizasyon tek yönlü mü, iki yönlü mü?

Kullandığınız özelliğe bağlıdır.

• Belirtim-Önce Modu iki yönlüdür: Apidog → Git ve Git → Apidog.
• Otomatik yedekleme tek yönlüdür: Apidog → Git.

Belirtimlerim nerede saklanıyor?

Bağladığınız Git deposunda saklanır.

Belirtim-Önce Modu'nda OpenAPI belgesi push yaptığınız dalda bulunur. Otomatik yedeklemede ise her modülün dışa aktarılmış OpenAPI/Swagger dosyası yapılandırılmış depoya commit edilir.

Hangi dala senkronize etmeliyim?

Standart belirtim için main, devam eden değişiklikler için feature branch kullanın. İnceleme gerektiren ekiplerde feature branch + pull request modeli daha güvenlidir.

Token iptal edilirse ne olur?

Apidog'un Git'e yazma erişimi kalmadığı için push işlemleri başarısız olur. Sağlayıcıyı yeniden yetkilendirin veya Azure DevOps/genel bağlantılar için yeni PAT oluşturup Apidog'da güncelleyin.

Sonuç

Apidog Git entegrasyonu iki tamamlayıcı kullanım sunar:

• Belirtim-Önce Modu: OpenAPI belirtimini kod gibi yönetmek, commit/push yapmak ve pull request ile incelemek için.
• Otomatik Git yedeklemesi: İş akışını değiştirmeden belirtimlerin sürümlü kopyasını Git'te tutmak için.

Her iki yaklaşım da GitHub, GitLab ve Azure DevOps ile çalışır. İnceleme, geçmiş ve geri alma mekanizması istiyorsanız Belirtim-Önce Modu'nu kullanın. Yalnızca güvenli ve sürümlü yedek istiyorsanız otomatik yedeklemeyi açın. Birçok ekip için en pratik çözüm ikisini birlikte kullanmaktır: günlük tasarım için iki yönlü senkronizasyon, ek güvenlik için otomatik yedekleme.