YAML i GitHub Actions — mønstre og fallgruver

Hver GitHub Actions-arbeidsflyt du har skrevet er en YAML-fil. Alt — utløsere, jobber, trinn, miljøvariabler, matrisestrategi — uttrykkes i YAML. Det betyr at en dyp forståelse av YAML ikke bare er akademisk: det er forskjellen mellom CI som fungerer pålitelig og CI som mystisk bryter sammen klokken 16 på en fredag når du prøver å slippe en release.

GitHub Actions har utmerket dokumentasjon om arbeidsflyt-syntaks, men den fokuserer på Actions-funksjonene snarere enn YAML-mekanikken under. Denne artikkelen dekker begge deler — arbeidsflytstrukturen og YAML-spesifikke mønstre (og fallgruver) som avgjør om CI-konfigurasjoner lykkes eller feiler.

Arbeidsflytstruktur: Nøklene på toppnivå

En GitHub Actions arbeidsflytfil ligger i .github/workflows/ og har tre påkrevde nøkler på toppnivå. Den offisielle arbeidsflytsoversikten forklarer hvor filen ligger i repoen din og hvordan GitHub oppdager den:

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

Utløsere: Nøkkelen on:

Nøkkelen on: styrer når arbeidsflyten din kjøres. Den fullstendige listen over utløserhendelser dekker alt fra pull request-gjennomganger til repository dispatches. Her er de vanligste mønstrene:

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]

Flerlinjede run:-kommandoer og YAML-blokkskalaer

Nøkkelen run: er der YAMLs bokstavelige blokkskalar (|) virkelig gjør nytten — se referansen på yaml-multiline.info for alle variasjoner av blokk- og foldede skalaer. Uten den ville du kjede kommandoer med && på én enkelt linje, noe som er uleselig:

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

Miljøvariabler og hemmeligheter

Miljøvariabler i GitHub Actions bruker YAML i kombinasjon med Actions kontekst- og uttrykkssyntaks. Slik passer de sammen:

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

Uttrykkssyntaksen ${{ }} er GitHub Actions' eget malspr̊ak oven på YAML. Det evalueres før YAML-parsing i noen kontekster, noe som kan interagere uventet med YAMLs egne siteringsregler. Omgi verdier som starter med ${{ i doble anførselstegn ved tvil.

Matrisestrategi: Bygg på tvers av flere konfigurasjoner

Matrisestrategien er en av GitHub Actions' mest kraftige funksjoner — og den uttrykkes utelukkende i YAML. Den kjører jobben din én gang for hver kombinasjon av matriseverdier:

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

Denne enkle jobdefinisjonen produserer opptil 9 parallelle kjøringer (3 OS × 3 Node-versjoner, minus 1 ekskludert). YAML-matriseverdiene er vanlige arrays — det eneste å se opp for er at versjonsnumre som 18 bør siteres som "18" for å holde dem som strenger. Uten anførselstegn tolker YAML dem som heltall, og noen Actions kan klage.

Betingede trinn med if:

Nøkkelen if: lar deg hoppe over trinn basert på betingelser. Den bruker GitHubs uttrykksspråk, ikke vanlige YAML-verdier:

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

Gjenbrukbare arbeidsflyter

For å eliminere duplisering på tvers av repositories (ikke bare innenfor en fil) støtter GitHub Actions gjenbrukbare arbeidsflyter. Den kalte arbeidsflyten bruker on: workflow_call: og den som kaller bruker uses: på jobbnivå — ikke trinnnivå:

# .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 }}

De vanligste YAML-feilene i GitHub Actions

• Feil innrykk på trinn. Trinn må rykkes inn under steps: med konsistente mellomrom. Et enkelt ekstra eller manglende mellomrom flytter et trinn utenfor jobben.
• Usiterte versjonsnumre. node-version: 20 sender et heltall; noen actions forventer en streng. Bruk node-version: "20" for sikkerhets skyld.
• Bruk av > i stedet for | for shell-skript. Foldede skalaer kollapser linjeskift. Det flerlinjede skriptet ditt blir én lang streng og feiler.
• Manglende anførselstegn på glob-mønstre. Mønstre som release/** inneholder * som YAML kan tolke som et alias. Siter alltid glob-mønstre.
• Hemmeligheter brukt i if:-betingelser. GitHub maskerer hemmeligheter i logger, men tillater dem ikke i if:-uttrykk. Bruk en miljøvariabel i stedet.
• Å glemme fail-fast: false i matrisejobber. Som standard avbrytes alle andre matrisejobber hvis én matrisejobb feiler. Vanligvis ikke hva du ønsker under feilsøking.

Oppsummering

GitHub Actions-arbeidsflyter er fundamentalt YAML-filer — forståelse av YAMLs bokstavelige blokkskalaer, siteringsregler og typetvang oversettes direkte til å skrive mer pålitelig CI. De vanligste feilene kommer fra innrykkfeil, usiterte verdier som konverteres til feil type, og bruk av feil flerlinjet strengoperator for shell-skript. Få de tre tingene riktig og det meste av arbeidsflyt-feilsøking blir rett fram. Bruk YAML-validatoren for å fange syntaksfeil før pushing, og YAML-formateringen for å håndheve konsistent innrykk på tvers av arbeidsflytfilene dine.