GitHub entegrasyonu

Pull request'leri Multica işlerine bağlayın ve geliştirme sürecini işin üzerinden izleyin.

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ştirmede-Bitti'ye taşıma 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 → Entegrasyonlar → Git barındırma'dır; 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:

Ayarlar → GitHub'ı açın.
GitHub entegrasyonu ana anahtarını açın.
GitHub'a Bağlan'a tıklayın.
GitHub'da hesabı veya organizasyonu seçin ve tüm depoları ya da seçtiğiniz bir alt kümeyi yetkilendirin.
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.

GitHub bağlantısı, Multica'nın hangi depolardan PR olayları alacağına karar verir; kod depoları ayarı ise agent'ların çalıştırma başlatırken hangi depoları seçebileceğine karar verir. Bunlar farklı amaçlara hizmet eder ve ayrı ayrı yapılandırılır.

Özellik anahtarları

Ayarlar → GitHub'da dört anahtar vardır:

Anahtar	Etki
GitHub entegrasyonu	Ana anahtar. Kapalıyken aşağıdaki üçü çalışmayı durdurur, ancak GitHub App bağlı kalır.
PR kenar çubuğu	İş detayında bağlı pull request'leri gösterir.
Co-authored-by	Agent'lar tarafından oluşturulan commit'lere `Co-authored-by: multica-agent <github@multica.ai>` ekler.
Otomatik PR bağlama	Bir PR'ın dal adında, başlığında ve gövdesinde iş tanımlayıcılarını algılar.
PR kartı → CI ve birleştirilebilirlik	Bağlı her PR için Multica, kimlik doğrulamalı bir GitHub API anlık görüntüsü alır ve CI durumunu ile birleştirilebilirliğini karta yansıtır (aşağıdaki PR kartı neler gösterir bölümüne bakın).

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, GitHub'ın kapama niyetlerinden birini kullanın:

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

Gövdedeki yalnızca referans niteliğindeki bir bahis, örneğin Related to MUL-123, o iş için çalışan bir PR olarak gösterilmez. Commit mesajları ve PR yorumları da bağlamayı tetiklemez.

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.

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ştirilmiş bir PR bir işi ne zaman Bitti'ye taşır

Birleştirilmiş bir PR, işin bittiği anlamına gelmek zorunda değildir. Multica bir işi yalnızca aşağıdakilerin tümü sağlandığında Done'a taşır:

bağlı, birleştirilmiş en az bir PR, hemen ardından tanımlayıcının geldiği bir kapama niyeti kullanmıştır, örneğin Closes MUL-123 (Closes login MUL-123 gibi arada kelime bulunan biçimler sayılmaz);
işin hâlâ Open veya Draft durumunda başka çalışan bir PR'ı yoktur (gövdedeki yalnızca referans niteliğindeki bahisler sayılmaz);
iş şu anda done veya cancelled değildir.

Dolayısıyla MUL-123'ü yalnızca dal adında veya başlıkta yazmak bağlantıyı kurar ama tek başına tamamlanmayı tetiklemez. Birleştirilmeden kapatılan bir PR da işi tamamlamaz.

Durum değişikliği zaman çizelgesine 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.

Bağlantıyı kesme

Ayarlar → GitHub'da Bağlantıyı Kes'e tıklamak 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:

Alan	Değer
Homepage URL	Multica ön ucunuzun adresi, örn. `https://multica.example.com`
Callback URL	Boş bırakın
Setup URL	`https://<api-host>/api/github/setup`, Redirect on update etkin olacak şekilde
Webhook URL	`https://<api-host>/api/webhooks/github`
Webhook secret	Uzun vadede saklayacağınız rastgele bir dize

Depo izinleri:

İzin	Seviye
Metadata	Salt okunur
Contents	Salt okunur; head commit'i birleştirilebilirlik ve CI özetiyle birlikte okuyan PR anlık görüntü sorgusu için gereklidir
Pull requests	Salt okunur
Checks	Salt okunur; CI durumunu göstermek için kullanılır
Commit statuses	Salt okunur; eski tarz durum CI'ını toplamak için kullanılır

Ş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.

Bu Webhook secret'tır, OAuth Client secret değildir. İki taraf farklı webhook secret'larına sahipse, GitHub teslimatları 401 invalid signature döner.

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 Bitti'ye 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 → GitHub'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 ve tanımlayıcının geçerli çalışma alanına ait olduğunu kontrol edin.
Tanımlayıcı gövdede ama gösterilmiyor: Closes MUL-123'e geçin veya tanımlayıcıyı dal adına ya da PR başlığına koyun.
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ş tamamlanmadı: PR'ın bir kapama niyeti kullandığını doğrulayın ve diğer bağlı PR'ların hâlâ Open veya Draft olup olmadığını kontrol edin.

Sonraki adımlar

İşler — durum geçişlerinin birleştirmede-Bitti'ye taşıma ile 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ı.

Bu sayfada