CI/CD entegrasyonu

Bu sayfa, Spitfire'da kayıtlı bir testi CI/CD pipeline'ınızdan (GitHub Actions, GitLab CI, Jenkins, Azure Pipelines…) nasıl koşturacağınızı, exit code'ların ne anlama geldiğini, performans budget'larını, PR/MR comment'lerini ve pipeline'dan karşılaştırmalı koşu (sürüm A/B) başlatmayı adım adım anlatır.

#Ne işe yarar

• Her pull request'te ya da her deploy'dan sonra yük testini elle uğraşmadan koşturur.
• Pipeline adımı koşunun bitmesini bekler ve sonuca göre exit code döndürür: eşik ya da budget kırıldıysa adım kırmızı olur, merge engellenebilir.
• --pr-comment ile pull request'e (GitHub) ya da merge request'e (GitLab) adım bazında p95, p99 ve hata oranını baseline (referans) koşuya göre gösteren bir özet yazar.
• --compare ile aynı testi iki ortama aynı anda uygular ve "yeni sürüm daha mı yavaş?" sorusuna istatistiksel bir kararla cevap verir.

Test controller'da koşar; CI makinesi yalnızca küçük bir CLI (spitfire) çalıştırır ve sonucu bekler. Yükü sizin runner'larınız üretir, CI makinesinin gücü önemli değildir.

#Ne zaman kullanılır

• Her pull request'te performansın gerilemediğinden emin olmak istediğinizde.
• Staging'e her deploy'dan sonra bir "duman testi" (kısa, düşük yüklü koşu) istediğinizde.
• Sürüm çıkmadan önce yeni sürümü canlıdakiyle karşılaştırmak istediğinizde (bkz. Sürüm karşılaştırma).
• Gece koşan testler için pipeline yerine Spitfire'ın kendi zamanlamasını da kullanabilirsiniz: Zamanlama ve izleme.

#Başlamadan önce

1. Spitfire'da koşturmak istediğiniz test kayıtlı olmalı ve en az bir kez web arayüzünden başarıyla koşmuş olmalı (testin doğru çalıştığını önce elle görün).
2. Token'ı oluşturacak kullanıcının o testi koşturma yetkisi olmalı. Admin her testi koşturabilir; user rolündeki bir kullanıcı ancak grubunda "çalıştırabilir" işaretli testleri koşturabilir. Test sayfasında salt görüntüleme rozeti görüyorsanız token'ınız da o testi koşturamaz.
3. CI makinesi Spitfire'ın web adresine (HTTP portu, Docker kurulumunda varsayılan 8470 ya da önündeki HTTPS adresi) erişebilmeli.

#API token oluşturma

CLI, Spitfire'a kişisel bir API token'ıyla bağlanır. Token, sahibinin o anki rolü ve gruplarıyla çalışır; yalnızca testleri listeleyebilir, doğrulayabilir, koşu ve karşılaştırmalı koşu başlatıp durdurabilir ve sonucu okuyabilir. Başka hiçbir şey yapamaz.

API token'ları sayfası

Adım adım:

1. Sağ üstteki profil menünüzü açın ve API token'ları'na tıklayın.
2. Token oluştur düğmesine basın. Yeni API token'ı penceresi açılır.
3. Token'a pipeline'ı tanıtan bir ad verin (ör. github-checkout-pr). Ad denetim kaydında görünür; hangi pipeline'ın koşu başlattığını buradan anlarsınız.
4. Geçerlilik süresini seçin (süresiz de olabilir). Süresi dolan token 401 alır.
5. Oluşturun. Token (sfpat_…) yalnız bu bir kez gösterilir: kopyalayın.
6. Token'ı CI'ınızın gizli değişkenine SPITFIRE_TOKEN adıyla kaydedin:
   • GitHub: Settings → Secrets and variables → Actions.
   • GitLab: Settings → CI/CD → Variables (Masked işaretli).
7. Pencerede Kopyaladım, kapat'a basın.

Yeni API token'ı penceresi

#CLI kurulumu

CLI ayrı bir paket kurulumu gerektirmez; controller kendi sürümünün CLI'ını sunar. Bu sayede CLI ile controller her zaman aynı sürümdedir.

• Linux (amd64):

  bashKopyala

  curl -fsSL "$SPITFIRE_URL/api/v1/runner-dist/spitfire-cli-linux-amd64.gz" | gunzip > spitfire && chmod +x spitfire

• Windows (PowerShell):

  powershellKopyala

  Invoke-WebRequest "$env:SPITFIRE_URL/api/v1/runner-dist/spitfire-cli-windows-amd64.exe" -OutFile spitfire.exe -UseBasicParsing

• Docker imajı: CLI, Spitfire imajının içinde de vardır:

  bashKopyala

  docker run --rm -e SPITFIRE_URL -e SPITFIRE_TOKEN algebransoft/spitfire spitfire cloud run "Ödeme akışı"

CLI iki ortam değişkenini okur:

Token oluşturulduğu çalışma alanında geçerlidir ve test adları orada aranır. Tüm çalışma alanlarını gören bir kurulum yöneticisinin token'ı --workspace ile çalışma alanını seçer.

Controller'ın sertifikası kendi kurumsal CA'nızla imzalıysa --ca kurum-ca.pem verin. --insecure sertifikayı hiç doğrulamaz; yalnızca deneme ortamında kullanın.

Token'ın hangi testleri gördüğünü denemek için:

./spitfire cloud tests            # tüm testler
./spitfire cloud tests ödeme      # adında "ödeme" geçenler

Her satırda testin kimliği, sürümü ve adı yazar; koşturamadığınız testlerin yanında (view only) görünür.

#Test sayfasındaki CI düğmesi

Hazır YAML'ı elle yazmanıza gerek yok. Test sayfasının üst kısmındaki CI düğmesi (CI'da koştur) o test için doldurulmuş örnekleri gösterir: Spitfire adresi ve test adı yerinde yazılıdır.

Test sayfası üst kısmı

1. Testler sayfasından testi açın.
2. Üstteki CI düğmesine basın. CI'da koştur penceresi açılır.
3. Pipeline'ınıza uyan sekmeyi seçin: GitHub Actions, GitLab CI, A/B (GitHub), Docker, Kabuk ya da PowerShell.
4. Sağ üstteki Kopyala ile metni alın ve pipeline dosyanıza yapıştırın.
5. Pencerenin altındaki API token'ı oluştur → bağlantısı sizi token sayfasına götürür.

CI'da koştur penceresi

Pencerenin altında exit code'lar da yazar: "0 geçti · 99 eşik kırıldı · 97 eşik koşuyu durdurdu · 2 yazma onayı yok (--confirm-writes) · 1 diğer hatalar."

GitLab CI sekmesi

#Pipeline'dan test koşturma

#GitHub Actions

En basit adım:

# GitHub Actions adımı
- name: Yük testi
  env:
    SPITFIRE_URL: https://spitfire.example.com
    SPITFIRE_TOKEN: ${{ secrets.SPITFIRE_TOKEN }}
  run: |
    curl -fsSL "$SPITFIRE_URL/api/v1/runner-dist/spitfire-cli-linux-amd64.gz" | gunzip > spitfire && chmod +x spitfire
    ./spitfire cloud run "Ödeme akışı"

Adım koşunun bitmesini bekler. Koşu bitince CLI özeti yazdırır ve sonuca göre çıkar.

#GitLab CI

# .gitlab-ci.yml — SPITFIRE_TOKEN: Settings → CI/CD → Variables (masked)
load-test:
  image: algebransoft/spitfire
  variables:
    SPITFIRE_URL: https://spitfire.example.com
  script:
    - spitfire cloud run "Ödeme akışı"

#Jenkins, Azure Pipelines ve diğerleri

Herhangi bir kabukta aynı iki satır yeterlidir:

export SPITFIRE_URL=https://spitfire.example.com
# SPITFIRE_TOKEN CI'ın gizli değişkeninden gelir
curl -fsSL "$SPITFIRE_URL/api/v1/runner-dist/spitfire-cli-linux-amd64.gz" | gunzip > spitfire && chmod +x spitfire
./spitfire cloud run "Ödeme akışı" --runners 2 -o summary.json
echo $?

Windows ajanında (Azure Pipelines, GitHub windows-latest, Jenkins):

$env:SPITFIRE_URL = 'https://spitfire.example.com'
Invoke-WebRequest "$env:SPITFIRE_URL/api/v1/runner-dist/spitfire-cli-windows-amd64.exe" -OutFile spitfire.exe -UseBasicParsing
.\spitfire.exe cloud run 'Ödeme akışı'
exit $LASTEXITCODE

#Sık kullanılan bayraklar

CI'dan başlatılan koşular ci etiketi ve pipeline notu alır, denetim kaydına token'ın adıyla geçer. CLI commit ve branch bilgisini GitHub Actions, GitLab CI, Jenkins ve Azure Pipelines ortamından kendisi okur; test sayfasındaki Sürüm trendi her koşuyu bu etiketle gösterir.

#Veri değiştiren testler

Test SQL/Mongo yazma, riskli Redis komutu ya da veri değiştirdiği işaretli HTTP isteği içeriyorsa CLI onu onaysız başlatmaz ve 2 ile çıkar. Bu üretim yazma korumasıdır. Gerçekten istiyorsanız komuta --confirm-writes ekleyin:

./spitfire cloud run "Sipariş oluşturma" --env staging --confirm-writes

#Exit code'lar

Düz koşu (--compare olmadan):

Karşılaştırmalı koşu (--compare) için exit code'lar farklıdır; aşağıda Pipeline üzerinden karşılaştırmalı koşu bölümüne bakın.

#Performans budget'ları

Performans bütçesi (budget), bir adım için üst sınırdır; ör. POST /orders p95 < 300 ms ya da hata oranı %1'in altında. Budget'ı aşan koşu, kırılan eşik gibi düşer: exit code 99 olur, koşu sayfası, karşılaştırma, rapor ve PR özeti bunu gösterir.

Adım adım budget eklemek:

1. Test sayfasını açın. Performans bütçeleri kartını bulun.
2. Kartın sağ üstündeki Düzenle'ye basın (yalnızca admin). Performans bütçelerini düzenle penceresi açılır.
3. Bütçe ekle'ye basın.
4. Adım sütununda Adım seçin… listesinden adımı seçin.
5. İstatistik seçin: p95, p99, p90, Ortalama, Maks. ya da Hata oranı.
6. Altında kalmalı sütununa sınırı yazın (süreler ms, hata oranı yüzde).
7. Gerekirse başka adımlar için tekrarlayın ve kaydedin.

Budget'lar testle birlikte tutulur ama test sürümlerine girmez: değişiklikten sonra başlayan koşular yeni sınırlarla değerlendirilir, eski koşular değişmez.

#PR ve MR comment'leri

--pr-comment, pull request'e (GitHub Actions) ya da merge request'e (GitLab CI) bir özet yazar:

• testin baseline (referans) koşusuna göre her adımın p95, p99 ve hata oranı,
• toleransın ötesinde kötüleşen yerde ⚠️, ör. `/checkout` p95: 212 ms → 250 ms (+18%) ⚠️,
• budget'lar ve eşikler.

Her push yeni bir comment eklemez; aynı comment'i günceller (test başına gizli bir işaretle bulunur). Comment'i yalnızca CI işi, pipeline'ın verdiği token'la yazar; controller GitHub'la ya da GitLab'la hiç konuşmaz.

#GitHub Actions

1. Workflow'a pull-requests: write izni verin.
2. Adımın env'ine GITHUB_TOKEN ekleyin.
3. Komuta --pr-comment (ve isterseniz --summary-md spitfire.md) ekleyin.

# .github/workflows/load-test.yml
on: [pull_request]
permissions:
  contents: read
  pull-requests: write          # PR yorumu
jobs:
  load-test:
    runs-on: ubuntu-latest
    steps:
      - env:
          SPITFIRE_URL: https://spitfire.example.com
          SPITFIRE_TOKEN: ${{ secrets.SPITFIRE_TOKEN }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          curl -fsSL "$SPITFIRE_URL/api/v1/runner-dist/spitfire-cli-linux-amd64.gz" | gunzip > spitfire && chmod +x spitfire
          ./spitfire cloud run "Ödeme akışı" --pr-comment --summary-md spitfire.md

--summary-md aynı Markdown'ı bir dosyaya yazar; GitHub'da özet iş sayfasına da düşer ($GITHUB_STEP_SUMMARY).

#GitLab CI

1. GitLab'da api kapsamlı bir proje erişim token'ı oluşturun.
2. Onu maskeli SPITFIRE_GITLAB_TOKEN değişkeni olarak kaydedin (yoksa CI_JOB_TOKEN denenir, ama çoğu GitLab sürümü onunla merge request notu yazdırmaz).
3. İşi merge request pipeline'ında koşturun.

# .gitlab-ci.yml — SPITFIRE_TOKEN: Settings → CI/CD → Variables (masked)
# SPITFIRE_GITLAB_TOKEN: proje erişim token'ı (api kapsamı), maskeli
load-test:
  image: algebransoft/spitfire
  variables:
    SPITFIRE_URL: https://spitfire.example.com
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  script:
    - spitfire cloud run "Ödeme akışı" --pr-comment --summary-md spitfire.md
  artifacts:
    when: always
    paths: [spitfire.md]

#Tolerans ve baseline

• --pr-tolerance 10: p95/p99'u baseline'a göre %10'dan fazla kötüleşen adımı ⚠️ ile işaretler. Verilmezse testin kendi toleransı geçerlidir.
• Testin baseline koşusu yoksa özet değerleri listeler ve baseline'ın nasıl seçileceğini söyler. Baseline, bir koşu sayfasındaki Baseline yap ile seçilir.

#Pipeline üzerinden karşılaştırmalı koşu

--compare, testi iki ortamına aynı anda ve aynı yükle uygular, kararı bekler, adım bazlı farkları yazdırır ve karara göre çıkar. Ayrıntılar için Sürüm karşılaştırma.

spitfire cloud run "Ödeme akışı" --compare A=test,B=dev --label-a v2.3 --label-b "$GIT_SHA"

Öncelik sırası: önce geçersiz ve daha kötü, sonra B kolunun eşikleri, sonra belirsiz.

Karşılaştırmaya özgü bayraklar: --label-a, --label-b, --fail-on-inconclusive, --strict, --compare-mode sequential, --rounds, --switch-timeout, --auto-switch. Bunlar --compare olmadan verilemez; --env ve --var ise --compare ile birlikte verilemez. --scale burada her kolun test yükündeki payıdır (varsayılan 0.5).

GitHub Actions örneği (test sayfasındaki A/B (GitHub) sekmesi de bunu verir):

# .github/workflows/version-compare.yml
on: [pull_request]
permissions:
  contents: read
  pull-requests: write
jobs:
  compare:
    runs-on: ubuntu-latest
    steps:
      - env:
          SPITFIRE_URL: https://spitfire.example.com
          SPITFIRE_TOKEN: ${{ secrets.SPITFIRE_TOKEN }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          curl -fsSL "$SPITFIRE_URL/api/v1/runner-dist/spitfire-cli-linux-amd64.gz" | gunzip > spitfire && chmod +x spitfire
          ./spitfire cloud run "Ödeme akışı" --compare A=test,B=dev \
            --label-a v2.3 --label-b "$GITHUB_SHA" --pr-comment --report comparison.pdf

GitLab CI örneği:

# .gitlab-ci.yml — SPITFIRE_TOKEN ve SPITFIRE_GITLAB_TOKEN maskeli değişken
version-compare:
  image: algebransoft/spitfire
  variables:
    SPITFIRE_URL: https://spitfire.example.com
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  script:
    - spitfire cloud run "Ödeme akışı" --compare A=test,B=dev --label-a v2.3 --label-b "$CI_COMMIT_SHORT_SHA" --pr-comment --fail-on-inconclusive --strict --report comparison.html
  artifacts:
    when: always
    paths: [comparison.html]

#Sık karşılaşılan sorunlar

#İlgili sayfalar

• Sürüm karşılaştırma — --compare'in arkasındaki istatistik ve karar
• Zamanlama ve izleme — pipeline olmadan düzenli koşular ve bildirimler
• Sorun giderme — hata kodları, sistem olayları, destek paketi
• API token'ları Spitfire'da: /api-tokens