Gyro Pipeline: git push ile otomatik derleme ve dağıtım

1. Nasıl çalışır

git push ─▶ webhook ─▶ derleme (yalıtılmış ortam, Dockerfile) ─▶ özel imaj deponuz ─▶ servisleriniz yeni sürüme geçer ─▶ sağlık kontrolü
                                                                                                          └─ geçmezse önceki sürüme döner

• Kaynak: GitHub, GitLab, Gitea / Forgejo, Bitbucket ya da her git sunucusu — https (özel depoda yalnız okuma belirteci) veya SSH (pipeline'a özel deploy key). Depo yoksa kodunuzu .tar.gz / .zip arşiv olarak yükleyip derleyebilirsiniz (Bölüm 4b).
• Derleme: Her çalıştırma kendi yalıtılmış derleme ortamında, Dockerfile'ınızla yapılır. Derleme ortamı internete çıkabilir (paket indirme vb.) ama Gyro'nun iç ağlarına erişemez.
• İmaj: registry.ist.gyrohosting.com/<ortam-kodu>/<imaj-adı>:<commit-kısa> ve :latest olarak İmaj Deposu'na konur.
• Dağıtım: Seçtiğiniz servisler bu imaja geçer; kopyalar teker teker yenilenir, siteniz kapanmaz. Yeni sürüm sağlık kontrolünü geçmezse servis kendiliğinden bir önceki sürüme döner.

2. Pipeline oluşturmak

1. Hizmetinizde Pipeline (CI/CD) sekmesini açın, Yeni pipeline'a basın.
2. Ad girin ve Kaynak seçin: Git deposu (https), Git deposu (SSH, deploy key) ya da Arşiv yükleme.
3. https için Sağlayıcı ve Depo adresi (https://github.com/kurum/uygulama); depo özelse Erişim belirteci (GitHub: fine-grained token, yalnız "Contents: Read"; GitLab: read_repository). Belirteç şifreli saklanır, hiçbir ekranda ve logda görünmez. SSH için adres [email protected]:kurum/uygulama.git biçimindedir; anahtar adımları Bölüm 3b'de.
4. Tetikleyen dallar (ör. main, release/*) ve isterseniz Tetikleyen etiketler (ör. v*) yazın.
5. İmaj adı (ör. web), Dockerfile yolu ve gerekiyorsa Derleme klasörü girin.
6. Dağıtılacak servisler'den bir ya da birkaç servis seçin. Boş bırakırsanız yalnız imaj üretilir.
7. Kaydet'e basın. Ekranda webhook adresi ve gizli anahtar görünür.

3. Webhook'u deponuza eklemek

GitHub: Depo → Settings → Webhooks → Add webhook

• Payload URL: panelde gösterilen webhook adresi
• Content type: application/json
• Secret: panelde gösterilen gizli anahtar
• Which events: Just the push event (etiketler de push olarak gelir)

GitHub hemen bir deneme (ping) gönderir; yeşil tik görmelisiniz.

GitLab: Proje → Settings → Webhooks: URL = webhook adresi, Secret token = gizli anahtar, Push events (+ etiket derlemek için Tag push events).

Gitea / Forgejo: Depo → Ayarlar → Webhook'lar → Gitea: hedef adres, POST, application/json, Gizli = gizli anahtar, tetikleyici Push.

Kendi sisteminiz / diğer git sunucuları: POST <webhook adresi> gövdesi {"ref":"refs/heads/main","sha":"<40 karakter commit>"}, başlıklar X-Gyro-Timestamp: <unix saniye> ve X-Gyro-Signature: sha256=HMAC_SHA256(gizli, zaman + "." + gövde).

Gizli anahtarı panelde Webhook → Göster ile yeniden görebilir, Yenile ile değiştirebilirsiniz (yeniledikten sonra depodaki ayarı da güncelleyin).

3b. Özel depo: SSH deploy key

Belirteç yerine depoya yalnız okuma yetkili bir deploy key tanımlamak isterseniz:

1. Kaynak olarak Git deposu (SSH, deploy key) seçin, adresi girin: [email protected]:kurum/uygulama.git ya da ssh://[email protected]:2222/ekip/uygulama.git (port 22, 443 ya da 1024 üstü).
2. Kaydedince SSH erişimi penceresi açılır. Deploy key oluştur'a basın. Gyro, bu pipeline'a özel bir ed25519 anahtar çifti üretir; ekranda yalnız açık anahtar ve parmak izi görünür. Özel anahtar şifreli saklanır, hiçbir ekranda, API yanıtında ya da logda gösterilmez.
3. Açık anahtarı deponuza salt okuma deploy key olarak ekleyin:
   • GitHub: Depo → Settings → Deploy keys → Add deploy key (Allow write access kapalı)
   • GitLab: Proje → Settings → Repository → Deploy keys
   • Bitbucket: Repository settings → Access keys
   • Gitea / Forgejo: Depo → Ayarlar → Dağıtım Anahtarları
4. Sunucu anahtarı (host key): GitHub, GitLab ve Bitbucket'ın yayımladığı anahtarlar sistemde sabittir, onay gerekmez. Kendi git sunucunuzda Sunucu anahtarını getir'e basın; gösterilen SHA256: parmak izini sunucu yöneticinizin kaydıyla karşılaştırıp Onayla'yın. Anahtar sonradan değişirse derleme durur ve sizi uyarır (araya girme saldırısına karşı).
5. Bağlantıyı test et dalları listeliyorsa hazırsınız. Webhook kurulumu https ile aynıdır (Bölüm 3).

Anahtarı Yenile ile değiştirebilir (eski anahtar hemen geçersiz olur, depodakini de değiştirin) ya da Silebilirsiniz.

4. İlk çalıştırma ve canlı log

• Deponuza bir commit push edin ya da pipeline kartında Şimdi çalıştır'a basıp dal veya etiket seçin (main, tag:v1.2.0).
• Çalıştırmalar listesinde durum sırayla: Sırada → Derleniyor (kod çekiliyor / komutlar / imaj derleniyor) → Dağıtılıyor → Sağlık kontrolü → Başarılı.
• Terminal simgesi canlı logu açar: Kod çekme, Derleme komutları ve İmaj derleme bölümleri ayrı görünür. Belirteç ve gizli değerler logda **** olur.
• Bir derleme sunucusu her zaman hazır bekler; derleme genelde birkaç saniye içinde başlar. Aynı anda çok derleme varsa ikinci sunucu birkaç dakikada açılır, o sırada "derleme sunucusu bekleniyor" görebilirsiniz.

4b. Arşivden derleme (.tar.gz / .zip)

Kodunuz bir git deposunda değilse ya da tek seferlik bir sürüm derlemek istiyorsanız:

1. Yeni pipeline'da kaynak olarak Arşiv yükleme seçin (ya da mevcut bir pipeline'da Arşivden derle düğmesini kullanın).
2. Arşiv seç ile .tar.gz, .tgz ya da .zip dosyanızı seçip Yükle ve derle'ye basın. Dosya en çok 200 MB olabilir; doğrudan nesne depolamaya yüklenir (ilerleme çubuğu görünür), ardından derleme başlar.
3. Arşivde Dockerfile kökte olmalı. Arşivin içinde tek bir üst klasör varsa (ör. GitHub'dan indirilen uygulama-main/) o klasör kök sayılır.

Güvenlik kuralları: bağlantılar (symlink / hardlink), aygıt dosyaları, / ile başlayan ya da ../ içeren yollar ve şifreli zip kabul edilmez; en çok 20.000 dosya, açılmış hali en çok 2 GB. Kural dışı arşiv "Arşiv güvenli değil ya da bozuk" hatası ve nedeniyle durur. Yüklenen arşivler en geç 24 saat sonra silinir. Arşiv derlemelerinde gyro-pipeline.yml okunmaz; panel ayarları geçerlidir. İmaj etiketi arc-<yükleme-kimliği> olur.

API ile: POST /cloud/containers/{id}/pipelines/{pipeline}/uploads {"size": <bayt>} → dönen url'e curl -T uygulama.tar.gz "<url>" → POST .../runs {"upload_id": "..."}.

5. Derleme komutları ve gyro-pipeline.yml

Dockerfile'dan önce test ya da hazırlık komutu çalıştırmak için Gelişmiş ayarlar'da Derleme komutları imajı (ör. node:22-alpine) ve her satıra bir komut yazın. Komutlar deponun kökünde çalışır; bir komut hata verirse derleme durur.

• Derleme değişkenleri (ANAHTAR=değer) ve Derleme gizli değerleri komutlara ortam değişkeni olarak verilir. Gizli değerler şifreli saklanır, geri okunamaz.
• Dockerfile build-arg değerleri ARG olarak gelir; imaj geçmişinde görünür, gizli değer yazmayın.
• Komutlarda GYRO_COMMIT (commit) ve GYRO_REF (dal/etiket) hazırdır.

Ayarları kodla birlikte tutmak isterseniz deponun köküne gyro-pipeline.yml koyun (GitHub, GitLab, Gitea). Dosya varsa paneldeki ayarların üzerine yazar:

image: web
dockerfile: Dockerfile
context: .
build:
  image: node:22-alpine
  commands:
    - npm ci
    - npm test
  env:
    NODE_ENV: production
  args:
    APP_VERSION: "1.0"
deploy:
  services: [web, worker]
  approval: false
  rollback: true

6. Onay, durdurma ve geri dönüş

• Dağıtımdan önce onay iste açıkken derleme bitince çalıştırma Onay bekliyor'da kalır; Onayla ve dağıt ya da Reddet. 24 saat içinde onaylanmazsa süresi dolar.
• Süren çalıştırmayı Durdur ile kesebilirsiniz.
• Bu sürüme dön (geri ok simgesi) daha önceki başarılı bir çalıştırmanın imajını hedef servislere yeniden dağıtır.
• Servis düzeyinde geri alma da çalışır: pipeline'ın her dağıtımı servisin Sürümler geçmişinde pipeline #N olarak görünür.

7. Bildirimler, sınırlar ve ücret

• Pipeline ayarındaki Bildirim kutuları (Başarısız, Geri alındı, Onay bekliyor, Başarılı) Uyarılar sayfasındaki kanallarınıza (e-posta, SMS, Telegram, imzalı webhook) gider.
• Varsayılan derleme kaynağı 2 vCPU / 4 GB, zaman sınırı 20 dakika; ortam başına aynı anda 1 derleme (sıradakiler bekler).
• Her ortamda ayda 300 derleme dakikası ücretsizdir. Bu ayki kullanım sekmenin üstünde görünür. Daha fazla dakika ya da paralel derleme için destek talebi açın.
• Derleme süresi, derlemenin derleme sunucusunda başlamasından bitişine kadar sayılır; bizden kaynaklanan hatalar sayılmaz.

8. Sık sorulan sorular

Derleme "Depoya erişim reddedildi" ile duruyor. Depo özel ve belirteç yok ya da okuma yetkisi yok. Pipeline Ayarlar → Erişim belirteci'ne yeni belirteç girin, Bağlantıyı test et ile deneyin.

Push yaptım ama çalıştırma başlamadı. Dal, Tetikleyen dallar kuralına uymuyor olabilir; ya da Webhook gelince otomatik derle kapalı. GitHub'da webhook'un Recent Deliveries bölümünde yanıt kodunu kontrol edin (202 = alındı, ignored: rule = kurala uymadı).

Derleme başarılı ama durum "Geri alındı". Yeni sürüm sağlık kontrolünü geçmedi (ör. kapsayıcı hemen çıkıyor). Servis eski sürümle çalışmaya devam eder; Loglar → Önceki örnek ile hatayı görün.