GitHub Actions'da YAML — Kalıplar ve Tuzaklar

Yazdığınız her GitHub Actions iş akışı bir YAML dosyasıdır. Tümü — tetikleyiciler, job'lar, adımlar, ortam değişkenleri, matrix strategy — YAML ile ifade edilir. Bu, YAML'ı derinlemesine anlamanın yalnızca akademik olmadığı anlamına gelir: güvenilir çalışan bir CI ile Cuma öğleden sonra bir sürüm çıkarmaya çalışırken gizemli şekilde bozulan bir CI arasındaki farktır.

GitHub Actions'ın mükemmel bir iş akışı sözdizimi belgeleri vardır, ancak bunlar alttaki YAML mekaniklerinden ziyade Actions özelliklerine odaklanır. Bu makale her ikisini de kapsar — iş akışı yapısını ve CI yapılandırmalarını belirleyen YAML'a özgü kalıpları (ve tuzakları).

İş Akışı Yapısı: Üst Düzey Anahtarlar

GitHub Actions iş akışı dosyası .github/workflows/ dizininde bulunur ve üç zorunlu üst düzey anahtara sahiptir. Resmi iş akışına genel bakış dosyanın deponuzda nerede bulunduğunu ve GitHub'ın onu nasıl keşfettiğini açıklar:

name: CI Pipeline          # optional but shown in the Actions UI

on:                        # triggers
  push:
    branches: [main]
  pull_request:

jobs:                      # the actual work
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test

Tetikleyiciler: on: Anahtarı

on: anahtarı, iş akışınızın ne zaman çalışacağını kontrol eder. Pull request incelemelerinden repository dispatch'lerine kadar her şeyi kapsayan tetikleyici olayların tam listesi mevcuttur. En yaygın kalıplar:

on:
  # Push to specific branches
  push:
    branches:
      - main
      - "release/**"       # glob pattern — quotes needed for /**
    paths-ignore:
      - "docs/**"
      - "*.md"

  # PRs targeting main
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened]

  # Scheduled (cron syntax)
  schedule:
    - cron: "0 2 * * 1"   # every Monday at 2am UTC

  # Manual trigger with input
  workflow_dispatch:
    inputs:
      environment:
        description: "Target environment"
        required: true
        default: staging
        type: choice
        options: [staging, production]

Çok Satırlı run: Komutları ve YAML Blok Skalarleri

run: anahtarı, YAML'ın literal block scalar (|) özelliğinin değerini kanıtladığı yerdir — blok ve folded skalarların her varyasyonu için yaml-multiline.info referansına bakın. Olmadan, komutları tek satırda && ile zincirlemek zorunda kalırsınız ve bu okunaksızdır:

steps:
  # Single line — works but hard to read
  - name: Build
    run: npm ci && npm run lint && npm run test && npm run build

  # Multi-line with literal block scalar — much better
  - name: Build
    run: |
      npm ci
      npm run lint
      npm run test -- --coverage
      npm run build

  # Folded scalar (>) joins lines with spaces — NOT what you want for shell
  # This would run as a single command with spaces where the newlines are:
  - name: Wrong for shell
    run: >
      npm ci
      npm test

Ortam Değişkenleri ve Gizli Bilgiler

GitHub Actions'daki ortam değişkenleri, YAML'ı Actions bağlamı ve ifade sözdizimi ile birlikte kullanır. Nasıl bir araya geldikleri:

env:
  NODE_ENV: production         # workflow-level env var
  API_VERSION: "2.1"          # quoted to force string type

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      DEPLOY_ENV: staging      # job-level env var (overrides workflow-level)

    steps:
      - name: Deploy to staging
        env:
          API_KEY: ${{ secrets.STAGING_API_KEY }}     # step-level, from secret
          DATABASE_URL: ${{ vars.STAGING_DB_URL }}    # step-level, from variable
        run: |
          echo "Deploying to $DEPLOY_ENV"
          ./scripts/deploy.sh

${{ }} ifade sözdizimi, YAML'ın üzerine katmanlanan GitHub Actions'ın kendi şablon dilidir. Bazı bağlamlarda YAML ayrıştırmasından önce değerlendirilir; bu, YAML'ın kendi tırnak kurallarıyla beklenmedik şekillerde etkileşime girebilir. Şüphe duyduğunuzda, ${{ ile başlayan değerleri çift tırnak içine alın.

Matrix Strategy: Birden Fazla Yapılandırmada Derleme

Matrix strategy, GitHub Actions'ın en güçlü özelliklerinden biridir — ve tamamen YAML ile ifade edilir. Job'ınızı her matrix değeri kombinasyonu için bir kez çalıştırır:

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false         # don't cancel other matrix jobs on failure
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node: ["18", "20", "22"]
        exclude:
          - os: windows-latest
            node: "18"         # skip this combination

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - run: npm ci && npm test

Bu tek job tanımı 9'a kadar paralel çalıştırma üretir (3 OS × 3 Node sürümü, eksi 1 dışarıda bırakılan). YAML matrix değerleri düz dizilerdir — dikkat edilmesi gereken tek şey, 18 gibi sürüm numaralarının dize olarak kalması için "18" şeklinde tırnak içine alınması gerektiğidir. Tırnak olmadan YAML bunları tamsayı olarak ayrıştırır ve bazı Action'lar şikayetçi olabilir.

if: ile Koşullu Adımlar

if: anahtarı, koşullara göre adımları atlamanıza olanak tanır. Düz YAML değerleri değil, GitHub'ın ifade dilini kullanır:

steps:
  - name: Run tests
    run: npm test

  - name: Upload coverage
    if: success() && github.ref == 'refs/heads/main'
    uses: codecov/codecov-action@v4

  - name: Notify on failure
    if: failure()
    uses: slackapi/slack-github-action@v1
    with:
      slack-message: "Build failed on ${{ github.ref }}"
      channel-id: "C12345ABC"
    env:
      SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}

  - name: Deploy (only on tag push)
    if: startsWith(github.ref, 'refs/tags/v')
    run: ./scripts/deploy.sh production

Yeniden Kullanılabilir İş Akışları

Depo genelinde tekrarı ortadan kaldırmak için (yalnızca bir dosya içinde değil), GitHub Actions yeniden kullanılabilir iş akışlarını destekler. Çağrılan iş akışı on: workflow_call: kullanır ve çağıran, adım düzeyinde değil job düzeyinde uses: kullanır:

# .github/workflows/reusable-test.yml (the reusable workflow)
on:
  workflow_call:
    inputs:
      node-version:
        required: false
        type: string
        default: "20"
    secrets:
      NPM_TOKEN:
        required: true

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
      - run: npm ci && npm test
        env:
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

# .github/workflows/ci.yml (the caller)
on: [push, pull_request]

jobs:
  run-tests:
    uses: my-org/shared-workflows/.github/workflows/reusable-test.yml@main
    with:
      node-version: "22"
    secrets:
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

GitHub Actions'da En Yaygın YAML Hataları

• Adımlarda yanlış girinti. Adımlar, tutarlı boşluklarla steps: altında girintilenmek zorundadır. Bir boşluk fazla veya eksik, bir adımı kendi job'ının dışına taşır.
• Tırnak içine alınmamış sürüm numaraları. node-version: 20 bir tamsayı geçirir; bazı action'lar dize bekler. Güvenli olmak için node-version: "20" kullanın.
• Shell betiklerinde | yerine > kullanmak. Folded skalalar yeni satırları daraltır. Çok satırlı betiğiniz tek uzun bir dizeye dönüşür ve başarısız olur.
• Glob kalıplarında tırnak eksikliği. release/** gibi kalıplar, YAML'ın alias olarak yorumlayabileceği * içerir. Glob kalıplarını her zaman tırnak içine alın.
• if: koşullarında gizli bilgi kullanımı. GitHub günlüklerde gizli bilgileri maskeler ancak if: ifadelerinde kullanımına izin vermez. Bunun yerine bir ortam değişkeni kullanın.
• Matrix job'larında fail-fast: false'u unutmak. Varsayılan olarak bir matrix job başarısız olursa diğerleri iptal edilir. Genellikle hata ayıklama sırasında istediğiniz bu değildir.

Özet

GitHub Actions iş akışları temelde YAML dosyalarıdır — YAML'ın literal block scalar'larını, tırnak kurallarını ve tür zorlamasını anlamak, doğrudan daha güvenilir CI yazmaya dönüşür. En yaygın başarısızlıklar girinti hatalarından, yanlış türe zorlanan tırnaksız değerlerden ve shell betikleri için yanlış çok satırlı dize operatörü kullanımından kaynaklanır. Bu üç şeyi doğru yapın ve çoğu iş akışı hata ayıklaması basit hale gelir. Push öncesinde sözdizimi hatalarını yakalamak için YAML Validator'ı, iş akışı dosyalarınızda tutarlı girinti uygulamak için YAML Formatter'ı kullanın.