GitLab CI/CD Rehberi: Pipeline, Cache ve Rules

GitLab CI, depo içinde yaşayan bir yapılandırma dosyasıyla çalışır: .gitlab-ci.yml. Bu dosya kök dizinde olduğu sürece GitLab her push'ta (veya tanımladığınız olaylarda) pipeline'ı tetikler. Bu rehber, orta seviye bir geliştiricinin test, derleme ve dağıtım adımlarını güvenli ve sürdürülebilir biçimde kurmasına odaklanır. Sürüm numarası vermiyorum; GitLab CI şeması geriye dönük uyumluluğa önem verir, ancak kullandığınız GitLab sürümünün özellik setini kendi kurulumunuzun dokümantasyonundan doğrulayın.

Önkoşullar

• GitLab üzerinde bir proje ve en az bir runner. GitLab.com'da paylaşımlı runner'lar varsayılan olarak açıktır; kendi sunucunuzda çalışıyorsa runner'ı ayrıca kaydetmeniz gerekir.
• Proje kökünde .gitlab-ci.yml dosyası.
• Dağıtım hedefine erişim için CI/CD değişkenleri (Settings → CI/CD → Variables). Hassas değerleri dosyaya yazmayın.

Temel yapı: stage, job, script

Pipeline'lar stage'lerden, stage'ler job'lardan oluşur. Aynı stage'deki job'lar paralel, farklı stage'ler sıralı çalışır. Bir stage'deki tüm job'lar başarılı olmadan sonraki stage başlamaz.

stages:
  - test
  - build

variables:
  NODE_ENV: "test"

test:
  stage: test
  image: node:20
  script:
    - npm ci
    - npm test

build:
  stage: build
  image: node:20
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 week

artifacts ile üretilen çıktı sonraki job'lara ve indirilebilir paketlere taşınır. expire_in vermezseniz artifact'lar varsayılan süre boyunca saklanır ve depolama şişer.

Önbellek ile artifact farkı

Bunları karıştırmak yaygın bir hatadır:

• cache: job'lar arasında yeniden kullanılacak geçici veri (örn. node_modules, paket indirme önbelleği). Kaybolursa pipeline yine çalışır.
• artifacts: bir job'ın ürettiği ve sonraki stage'lerin ihtiyaç duyduğu çıktı. Kaybolursa pipeline kırılır.

default:
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - node_modules/

key olarak kilit dosyasını vermek, bağımlılıklar değiştiğinde önbelleğin yenilenmesini sağlar. Sabit bir anahtar kullanırsanız eski bağımlılıklar yapışıp kalır.

Kurallarla ne zaman çalışacağını belirlemek

only/except yerine rules kullanın; daha okunur ve esnektir.

deploy:
  stage: deploy
  script:
    - ./deploy.sh
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: manual
    - when: never

Burada deploy yalnızca main dalında görünür ve manuel onay bekler; diğer durumlarda hiç oluşturulmaz. when: never satırını unutursanız kural eşleşmediğinde job varsayılan davranışla çalışabilir.

Değişkenler ve sırlar

• Sırları asla .gitlab-ci.yml içine yazmayın. Proje, grup veya instance düzeyinde CI/CD değişkeni tanımlayın.
• Hassas değişkenleri "Masked" ve gerekiyorsa "Protected" işaretleyin. Protected, değişkenin yalnızca korumalı dal/etiketlerde görünmesini sağlar.
• Masked değişkenlerin log'da gizlenmesi belirli biçim kurallarına bağlıdır; çok kısa veya özel karakter içeren değerler maskelenmeyebilir. Değeri log'a basacak komutlardan (echo, set -x) kaçının.
• CI_JOB_TOKEN gibi öntanımlı değişkenler kısıtlı yetkiye sahiptir; bunları geniş yetkili erişim token'ı yerine tercih edin.

İş akışı kuralları

workflow:rules ile pipeline'ın tümüyle oluşturulup oluşturulmayacağını kontrol edebilirsiniz. Örneğin yalnızca merge request ve ana dal için pipeline üretmek gereksiz koşuları engeller.

workflow:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == "main"'
    - when: never

Matrix ile tekrarı azaltmak

Birden çok sürüm veya ortam için aynı job'ı kopyalamak yerine parallel:matrix kullanın.

test:
  stage: test
  image: "node:${NODE_VERSION}"
  parallel:
    matrix:
      - NODE_VERSION: ["18", "20", "22"]
  script:
    - npm ci
    - npm test

Bu, üç ayrı job üretir; her biri farklı imajda çalışır. Kullandığınız imaj etiketlerinin gerçekten var olduğundan emin olun.

Yaygın hatalar

• Yanlış stage adı: stages listesinde tanımlanmayan bir stage'e job atamak yapılandırmayı geçersiz kılar.
• script içinde cd sonrası kaybolan bağlam: Her job temiz bir çalışma dizininde başlar; önceki job'ın dosya sistemi durumuna güvenmeyin. Paylaşılması gerekenler artifacts ile taşınmalı.
• Artifact'ı çok geniş tanımlamak: Tüm depoyu artifact yapmak pipeline'ı yavaşlatır ve depolamayı tüketir. Yalnızca gerekli yolları listeleyin.
• allow_failure'ı farkında olmadan kullanmak: Güvenlik veya test job'larında bu, kırık bir pipeline'ı yeşil gösterir.
• Önbelleği sır sanmak: cache içeriği runner üzerinde paylaşılabilir; oraya sır koymayın.
• Sürümleri sabitlememek: image: node:latest gibi etiketler zamanla değişir ve pipeline'ı habersizce kırar. Belirli bir etiket veya digest kullanın.

Güvenlik etkileri

• Merge request pipeline'ları ve fork'lar: Dış katkı sağlayan fork'lardan gelen pipeline'lar varsayılan olarak korumalı değişkenlere ve runner'lara erişemez. Bunu gevşetmek, kötü niyetli bir merge request'in sırlarınıza veya altyapınıza erişmesine yol açabilir.
• Korumalı dal ve ortamlar: Üretim dağıtımını yalnızca korumalı dal ve korumalı ortam üzerinden çalıştırın; böylece kimlerin tetikleyebileceğini kontrol edersiniz.
• Manuel onay: Üretim adımlarını when: manual ile durdurmak, kazara dağıtımı engeller; ancak onay yetkisini de sınırlandırın.
• Runner izolasyonu: Paylaşımlı runner'da çalışan job'lar aynı host'u paylaşabilir. Hassas işler için ayrılmış runner tercih edin.
• Üçüncü taraf imajlar: image olarak kullandığınız imajları güvenilir kaynaklardan seçin ve sabitleyin; keyfi imajlar supply chain riski taşır.

Dağıtım adımını güvenli kurmak

Tipik bir üretim job'ı şu iskelete oturur:

deploy_production:
  stage: deploy
  environment:
    name: production
    url: https://example.com
  script:
    - ./deploy.sh
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: manual

environment tanımı, dağıtım geçmişini GitLab arayüzünde görünür kılar ve geri alma (rollback) işlemlerini kolaylaştırır. url alanına kendi ortamınızın adresini yazın.

Yapılandırmayı doğrulamak

Pipeline'ı push etmeden önce yapılandırmayı kontrol edin. GitLab arayüzünde CI Lint aracı vardır; ayrıca .gitlab-ci.yml içeriğini bu araca yapıştırarak sözdizimi ve mantık hatalarını yakalayabilirsiniz. Yeni bir job eklediğinizde önce küçük bir dalda denemek, ana dalı kırma riskini azaltır.

Kapanış

GitLab CI'ın gücü, yapılandırmayı kod olarak tutmasından gelir. Sağlam bir kurulum için üç şeye dikkat edin: job'lar arası veri akışını artifacts ile açıkça tanımlamak, sırları CI/CD değişkenleri üzerinden yönetmek ve üretim adımlarını korumalı dal, ortam ve manuel onayla sınırlamak. Bu ilkeler, eklentiler ve GitLab sürümleri değişse de geçerliliğini korur.