GitHub entegrasyonu

GitHub bağlandıktan sonra Multica, pull request'leri iş tanımlayıcılarına göre otomatik olarak bağlar. İş detayı; PR durumunu, değişiklik büyüklüğünü, CI sonuçlarını ve birleştirme çakışmalarını yerinde gösterir.

GitHub entegrasyonu yalnızca kurulum anında yetkilendirilen depoları okur; commit, yorum veya durum kontrolünü asla GitHub'a geri göndermez (push).

Kendi sunucunuzda barındırılan Multica, aynı PR otomatik bağlama, birleştirmeye bağlı durum değişiklikleri ve CI görüntüleme özellikleriyle kendi sunucunuzda barındırılan Forgejo, Gitea veya GitLab örneklerine de paralel olarak bağlanabilir. Giriş noktası Ayarlar → Kod'dur; bkz. Kendi sunucunuzda Git barındırma. Multica Cloud bu giriş noktasını sunmaz.

GitHub'ı Bağlayın

Bağlantıyı bir çalışma alanı sahibi veya yöneticisi tamamlayabilir:

1. Ayarlar → Kod'u açın.
2. GitHub satırında GitHub'a Bağlan'a tıklayın.
3. GitHub'da hesabı veya organizasyonu seçin ve tüm depoları ya da seçtiğiniz bir alt kümeyi yetkilendirin.
4. Kurulum tamamlandıktan sonra Multica'ya dönün.

Bağlantı durumu aynı sayfada gösterilir. Normal üyeler durumu görüntüleyebilir ama bağlanamaz, bağlantıyı kesemez veya anahtarları değiştiremez.

Özellik anahtarları

Ayarlar → Kod'un Pull request'ler ve işler bölümünde şu ayarlar bulunur. GitHub satırının ⋯ menüsündeki GitHub özelliklerini duraklat, GitHub App bağlantısını kesmeden aşağıdaki üç anahtarı durdurur.

PR'lar birleştikten sonra işi şuraya taşı, kendi sunucunuzda Git barındırma dahil her kod barındırıcısı için geçerlidir.

Bir PR'ı bir işe bağlama

En basit yaklaşım, iş tanımlayıcısını dal adına veya PR başlığına koymaktır. Örneğin MUL-123 işi için:

mul-123-fix-login-redirect

MUL-123 Fix the redirect after login

Multica büyük/küçük harfi yok sayar ve yalnızca geçerli çalışma alanının iş ön ekiyle eşleşir. Bir PR birden fazla işe bağlanabilir.

Tanımlayıcı yalnızca PR gövdesinde görünüyorsa, onu bir kapatma anahtar kelimesinin hemen ardına koyun:

Closes MUL-123
Fixes MUL-123
Resolves MUL-123

Gövdedeki çıplak bir bahis, örneğin Related to MUL-123, PR'ı hiç bağlamaz. Commit mesajları ve PR yorumları da bağlamayı tetiklemez.

Bir PR'ı elle de bağlayabilirsiniz: işin Pull requests bloğunda +'ya tıklayın ve PR URL'sini yapıştırın. Bir PR'ı işten çıkarmak için satırındaki ⋯ menüsünü açın ve İşten kaldır'ı seçin; Multica onu başlığından veya dalından yeniden bağlamaz.

Bir işteki PR'ları görüntüleme

Bağlandıktan sonra, PR'lar iş detayının Pull requests bloğunda görünür. Her giriş şunları gösterir:

• depo, numara, başlık ve yazar;
• Open, Draft, Merged veya Closed durumu;
• eklenen ve silinen satırlar ile değişen dosya sayısı;
• CI durumu: tümü geçti (sayısıyla birlikte), bazıları başarısız oldu (başarısız kontrolleri adlandırarak) veya bazıları devam ediyor; hiç kontrol yapılandırılmamış PR'lar bu öğeyi göstermez — "kontrol yok" hiçbir zaman geçti olarak sayılmaz;
• birleştirilebilirlik: birleştirilebilir (yalnızca GitHub temiz bir birleştirme durumu bildirdiğinde), çakışan, engellenmiş veya geride.

CI durumu ve birleştirilebilirlik, Multica'nın GitHub API'sinden çektiği anlık görüntülerden gelir ve ikisi birbirinden bağımsızdır; birleştirilmiş veya kapatılmış PR'lar artık ikisini de göstermez. GitHub geçici olarak erişilemez olduğunda, kart boş kalmak yerine son anlık görüntüyü korur ve onu bayat olarak işaretler.

Listenin altındaki bir satır bundan sonra ne olacağını söyler — örneğin #19 birleştiğinde Done'a taşınır ya da hangi PR'ın birleştirilmeden kapandığı. Çalışma alanı durumu değiştirmemeyi seçtiyse veya iş zaten hedef durumdaysa bu satır görünmez.

PR'ı GitHub'da açmak için bir girişe tıklayın. PR kenar çubuğu'nu kapatmak yalnızca bu bloğu gizler; hiçbir şeyin bağlantısını kesmez.

Birleştirilen PR'lar bir işi ne zaman taşır

Birleştirilmiş bir PR, işin bittiği anlamına gelmek zorunda değildir; bu yüzden birleştirmenin ne yapacağına çalışma alanı karar verir: Ayarlar → Kod → PR'lar birleştikten sonra işi şuraya taşı. Done'u (yeni çalışma alanları için varsayılan), başka bir başlamış veya bitmiş durumu — Regresyon bekliyor gibi özel bir durum da olur — ya da Değiştirme'yi seçin. Bu ayardan önce var olan çalışma alanları davranışlarını korur: birleştirme işlerini her zaman tamamlamıyorduysa, Değiştirme ile başlarlar.

Bir iş, aşağıdakilerin tümü sağlandığında seçilen duruma taşınır:

1. bağlı her PR Merged durumundadır — Open veya Draft bir PR işi bekletir; birleştirilmeden kapatılan bir PR da, siz onu işten kaldırana kadar bekletir;
2. iş done veya cancelled değildir, Triage'da değildir, zaten hedef durumda değildir ve bu iş için kapatılmamıştır (Pull requests → ⋯ → PR'lar birleştiğinde durumu koru).

PR'ın nasıl bağlandığı önemli değildir: başlık, dal adı ve gövdedeki bir Closes MUL-123 onu bağlar ve hiçbiri birleştirmenin ne yapacağını değiştirmez. Bir PR işin yalnızca bir kısmını teslim ediyorsa veya birleştirmenin ardından bir sürüm ya da kontrol gelmesi gerekiyorsa, o işin durumunu Pull requests menüsünden koruyun.

Kontrol, bir PR olayı işe dokunduğunda çalışır: bağlı bir PR birleştiğinde, bir PR bağlandığında veya bir bağlantı kaldırıldığında. Bir işi yeniden açmak onu geri taşımaz — bunu birleşen bir sonraki bağlı PR yapar. Ayarı değiştirmek, PR'ları daha önce birleşmiş işleri taşımaz.

Durum değişikliği zaman çizelgesine PR'ları adlandıran bir sistem eylemi olarak yazılır ve işe abone olan üyelere bildirim gönderilir.

Birden fazla çalışma alanı

Aynı GitHub App kurulumu birden fazla Multica çalışma alanına bağlanabilir. GitHub olayları her çalışma alanına ayrı ayrı akar ve her çalışma alanının kendi iş ön ekine göre eşleştirilir.

Örneğin, hem MUL-1 hem ENG-2'ye referans veren bir PR, farklı ön eklere sahip iki çalışma alanına bağlanabilir. Çalışma alanları birbirinin işlerini asla görmez.

Bir tanımlayıcı bağlı çalışma alanlarından birden fazlasında bir işle eşleşirse (aynı ön eki paylaştıklarında mümkündür), Multica onu hiçbirinde otomatik olarak bağlamaz; böylece PR'ı birleştirmek alakasız bir işi tamamlayamaz. PR'ı doğru çalışma alanında elle bağlayın.

Bağlantıyı kesme

Ayarlar → Kod'daki GitHub satırının ⋯ menüsünden Bağlantıyı Kes'i seçmek yalnızca geçerli Multica çalışma alanı ile kurulum arasındaki ilişkiyi kaldırır; App'i sizin adınıza GitHub'dan kaldırmaz. Mevcut PR kayıtları saklanır ve yeni olaylar o çalışma alanına akmayı durdurur.

GitHub tarafında depo yetkilendirmesini iptal etmek için App'i kaldırın veya kişisel ya da organizasyon GitHub App kurulumları sayfanızdan depo kapsamını ayarlayın. Kaldırdıktan sonra, o kuruluma bağlı her Multica çalışma alanı olay almayı durdurur.

Kendi sunucunuzda barındırma kurulumu

Multica Cloud bu bölüme ihtiyaç duymaz. Kendi sunucunuzda barındırma için önce kendi GitHub App'inizi oluşturmanız gerekir.

1. Bir GitHub App oluşturun

App'i GitHub'ın Developer settings → GitHub Apps altında oluşturun ve aşağıdakileri doldurun:

Depo izinleri:

Şu olaylara abone olun:

• Pull request;
• CI ve birleştirilebilirlik yenilemelerini tetikleyen Check suite, Check run ve Status.

Multica'da CI'ın gösterilmesine ihtiyacınız yoksa, Checks ve Commit statuses izinlerini ve bunların olaylarını atlayabilirsiniz. Contents yine de gereklidir — o olmadan anlık görüntü sorgusu tamamen başarısız olur ve PR kartı da birleştirme durumunu kaybeder.

2. Ortam değişkenlerini ayarlayın

Kısa adı (slug) App'in herkese açık URL'sinden alın. Örneğin https://github.com/apps/multica-acme adresinin kısa adı multica-acme'dir.

GITHUB_APP_SLUG=multica-acme
GITHUB_WEBHOOK_SECRET=<the webhook secret you entered when creating the App>
FRONTEND_ORIGIN=https://multica.example.com

GITHUB_APP_SLUG veya GITHUB_WEBHOOK_SECRET'tan biri eksikse, bağlan düğmesi devre dışı kalır ve webhook uç noktası olayları işlemeyi reddeder.

Sonraki iki değişken, PR kartının CI durumunu ve birleştirilebilirliği gösterebilmesi için gereklidir — Multica bunları App olarak kimlik doğrulamak ve anlık görüntüleri çekmek için kullanır:

GITHUB_APP_ID=<the GitHub App's numeric ID>
GITHUB_APP_PRIVATE_KEY=<full PEM private key, keeping the BEGIN/END lines and newlines>

Özel anahtarı GitHub App'in Private keys → Generate a private key bölümünde üretin. Bunlar olmadan entegrasyon zarifçe geriler: PR'lar yine yansıtılır, işler yine otomatik bağlanır ve birleştirmede taşınır — PR kartı yalnızca CI veya birleştirme durumu göstermez.

3. Veritabanını güncelleyin ve bağlanın

Mevcut bir dağıtımı yükseltirken, önce olağan veritabanı migration'larını çalıştırın:

make migrate-up

API sunucusunu yeniden başlatın, ardından bağlantıyı Ayarlar → Kod'da tamamlayın.

Sorun giderme

• Bağlan düğmesi devre dışı: GITHUB_APP_SLUG ve GITHUB_WEBHOOK_SECRET'ın API sürecine ulaştığını kontrol edin.
• Webhook 401 döndürüyor: GitHub App ile API'nin aynı webhook secret'ını kullandığını doğrulayın, ardından GitHub'ın Recent Deliveries sayfasından yeniden teslim edin.
• PR bağlanmadı: deponun App'in yetkilendirilmiş kapsamında olduğunu, otomatik bağlamanın açık olduğunu, tanımlayıcının geçerli çalışma alanına ait olduğunu ve kimsenin PR'ı işten kaldırmadığını kontrol edin.
• Tanımlayıcı gövdede ama bağlanmadı: onu bir kapatma anahtar kelimesinin hemen ardına (Closes MUL-123), dal adına ya da PR başlığına koyun veya PR'ı elle bağlayın.
• CI durumu yok: GITHUB_APP_ID ve GITHUB_APP_PRIVATE_KEY'in yapılandırıldığını ve App'in salt okunur Contents, Checks ve Commit statuses izinlerine sahip olduğunu, ilgili olaylara abone olunduğunu doğrulayın. Contents olmadan tüm anlık görüntü başarısız olur, bu yüzden PR kartı ne CI ne de birleştirme durumu gösterir. Kurulu bir App'e izin ekledikten sonra, her kurulumun sahibinin de bunları GitHub'da onaylaması gerekir ki etkili olsunlar.
• PR birleştirildikten sonra iş taşınmadı: işin Pull requests listesinin altındaki satırı okuyun. Satır hâlâ açık olan veya birleştirilmeden kapatılan PR'ları adlandırır ya da işin PR'lar birleştiğinde durumunu koruduğunu söyler. Satır yoksa çalışma alanı ayarı Değiştirme'dir veya iş zaten hedef durumdadır.

Sonraki adımlar

• İşler — durum geçişlerinin birleştirilen PR'larla ilişkisi.
• Proje kaynakları — agent'ların çalışırken hangi depoları kullandığı.
• Ortam değişkenleri — kendi sunucunuzda barındırılan GitHub App yapılandırmasının tamamı.