YAML i GitHub Actions — mönster och fallgropar

Varje GitHub Actions-arbetsflöde du har skrivit är en YAML-fil. Allt — triggers, jobb, steg, miljövariabler, matrisstrategi — uttrycks i YAML. Vilket innebär att en djup förståelse av YAML inte bara är akademiskt: det är skillnaden mellan CI som fungerar pålitligt och CI som mystiskt går sönder klockan 16 på en fredag när du försöker skicka en release.

GitHub Actions har utmärkt dokumentation om arbetsflödessyntax, men den fokuserar på Actions-funktionerna snarare än YAML-mekaniken under. Den här artikeln täcker båda — arbetsflödesstrukturen och YAML-specifika mönster (och fallgropar) som avgör om CI-konfigurationer lyckas eller misslyckas.

Arbetsflödesstruktur: Nycklarna på toppnivå

En GitHub Actions-arbetsflödesfil ligger i .github/workflows/ och har tre obligatoriska nycklar på toppnivå. Den officiella arbetsflödesöversikten förklarar var filen ligger i ditt repo och hur GitHub hittar 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

Triggers: Nyckeln on:

Nyckeln on: styr när ditt arbetsflöde körs. Den fullständiga listan över triggerhändelser täcker allt från pull request-granskningar till repository dispatches. Här är de vanligaste mönstren:

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]

Flerlinjiga run:-kommandon och YAML-blockskalar

Nyckeln run: är där YAMLs litterala blockskalar (|) verkligen visar sitt värde — se referensen på yaml-multiline.info för varje variant av block- och vikta skalar. Utan den skulle du kedja kommandon med && på en enda rad, vilket är oläsbart:

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 och hemligheter

Miljövariabler i GitHub Actions använder YAML i kombination med Actions kontext- och uttryckssyntax. Så här hör de ihop:

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

Uttryckssyntaxen ${{ }} är GitHub Actions' eget mallspråk ovanpå YAML. Det utvärderas innan YAML-parsning i vissa sammanhang, vilket kan interagera oväntat med YAMLs egna citatregler. Vid tvivel, omge värden som börjar med ${{ med dubbla citattecken.

Matrisstrategi: Bygg på flera konfigurationer

Matrisstrategin är en av GitHub Actions mest kraftfulla funktioner — och den uttrycks helt i YAML. Den kör ditt jobb en gång för varje kombination av matrisvärden:

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

Den här enda jobbdefinitionen producerar upp till 9 parallella körningar (3 OS × 3 Node-versioner, minus 1 undantagen). YAML-matrisvärdena är vanliga arrayer — det enda att se upp med är att versionsnummer som 18 bör citeras som "18" för att hålla dem som strängar. Utan citattecken tolkar YAML dem som heltal och vissa Actions kan klaga.

Villkorliga steg med if:

Nyckeln if: låter dig hoppa över steg baserat på villkor. Den använder GitHubs uttrycksspråk, inte vanliga YAML-värden:

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

Återanvändbara arbetsflöden

För att eliminera duplicering över repositories (inte bara inom en fil) stöder GitHub Actions återanvändbara arbetsflöden. Det anropade arbetsflödet använder on: workflow_call: och anroparen använder uses: på jobbnivå — inte stegnivå:

# .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 vanligaste YAML-misstagen i GitHub Actions

• Fel indragning på steg. Steg måste dras in under steps: med konsekventa mellanslag. Ett enda extra eller saknat mellanslag flyttar ett steg utanför dess jobb.
• Ociterade versionsnummer. node-version: 20 skickar ett heltal; vissa actions förväntar sig en sträng. Använd node-version: "20" för säkerhets skull.
• Användning av > istället för | för shell-skript. Vikta skalar kollapsar radbrytningar. Ditt flerlinjiga skript blir en lång sträng och misslyckas.
• Saknade citattecken på glob-mönster. Mönster som release/** innehåller * som YAML kan tolka som ett alias. Citera alltid glob-mönster.
• Hemligheter som används i if:-villkor. GitHub maskerar hemligheter i loggar men tillåter dem inte i if:-uttryck. Använd en miljövariabel istället.
• Att glömma fail-fast: false i matrisjobb. Som standard avbryts alla andra matrisjobb om ett matrisjobb misslyckas. Vanligtvis inte vad du vill vid felsökning.

Sammanfattning

GitHub Actions-arbetsflöden är fundamentalt YAML-filer — att förstå YAMLs litterala blockskalar, citatregler och typkonvertering översätts direkt till att skriva mer pålitlig CI. De vanligaste felen kommer från indragningsmisstag, ociterade värden som konverteras till fel typ och användning av fel flerlinjig strängoperator för shell-skript. Få rätt på de tre sakerna och det mesta av arbetsflödesfelsökning blir okomplicerat. Använd YAML-valideraren för att fånga syntaxfel innan pushning, och YAML-formateraren för att upprätthålla konsekvent indragning i dina arbetsflödesfiler.