# Gyro Pipeline: git push ile otomatik derleme ve dağıtım https://www.gyrohosting.com/bilgi-bankasi/makale/gyro-kapsayici-pipeline - **Bu rehberde ne öğreneceksiniz**: Kod deponuzu Gyro Kapsayıcı ortamınıza bağlamayı; her `git push`'ta kodun Dockerfile ile derlenip servislerinize kesintisiz dağıtılmasını, derleme logunu canlı izlemeyi ve gerektiğinde önceki sürüme dönmeyi. - **Süre**: 10 dakika - **Kimin için**: Uygulamasını Gyro Kapsayıcı'da çalıştıran geliştiriciler. - **Gerekenler**: Aktif bir Gyro Kapsayıcı (ECS) hizmeti, en az bir servis ve kök klasöründe Dockerfile olan bir git deposu. ## 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//:` 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 `git@github.com: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 ` gövdesi `{"ref":"refs/heads/main","sha":"<40 karakter commit>"}`, başlıklar `X-Gyro-Timestamp: ` 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: `git@github.com:kurum/uygulama.git` ya da `ssh://git@git.kurum.com: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 **Sil**ebilirsiniz. > SSH ile bağlanan **özel** depolarda `gyro-pipeline.yml` okunamaz (dosya sağlayıcının https adresinden okunur); ayarları panelden yapın ya da ek olarak okuma belirteci tanımlayın. ## 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-` olur. API ile: `POST /cloud/containers/{id}/pipelines/{pipeline}/uploads {"size": }` → dönen `url`'e `curl -T uygulama.tar.gz ""` → `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 **Kök kullanıcı gerektiren komutlar çalışır mı?** Derleme ortamında evet (yalıtılmış). Çalışan servisleriniz ise kök olmayan kullanıcıyla başlar; imajınızın 1024 üstü bir portu dinlediğinden emin olun. **SSH deploy key'i kendi anahtarımla değiştirebilir miyim?** Hayır; anahtar Gyro'da üretilir ve özel kısmı hiçbir yerde gösterilmez. Bu sayede anahtar başka sistemde kullanılamaz. Gerekirse **Yenile** ile yenisini üretin. **"SSH sunucusu onaylı anahtardan farklı bir anahtar gösteriyor" hatası aldım.** Git sunucunuzun anahtarı değişmiş ya da araya giren bir bağlantı var. Sunucu yöneticinizle yeni parmak izini doğrulayın, **SSH erişimi** → **Onayı kaldır** → **Sunucu anahtarını getir** → **Onayla**. **Arşiv yüklemesi yarıda kaldı.** Yükleme adresi 15 dakika geçerlidir; **Arşivden derle** ile yeniden başlatın. Yarım kalan yüklemeler derlenmez ve 24 saatte silinir. **API, CLI ya da Terraform ile yönetebilir miyim?** Evet: `/cloud/containers/{id}/pipelines` uçları (arşiv için `.../uploads`, SSH için `.../deploy-key` ve `.../host-key`), `gyro container pipeline ...` komutları ve `gyro_container_pipeline` Terraform kaynağı (`deploy_key = true`, `ssh_host_fingerprint`). Ayrıntı: Bilgi Merkezi → *Gyro Kapsayıcı: API, CLI ve Terraform*. **Örnek proje var mı?** `https://github.com/Gyro-Hosting/gyro-pipeline-ornek` deposunu çatallayıp (fork) 8080 portlu `web` servisinize bağlayabilirsiniz. **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.