GitHub Actions Workflow YAML Structure

GitHub Actions workflows are defined in YAML files under .github/workflows/. Understanding their JSON structure helps when generating workflows programmatically or debugging action configurations.

A typical GitHub Actions workflow:

name: CI Pipeline

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18, 20, 22]
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: npm
      - run: npm ci
      - run: npm test
      - run: npm run build

The JSON equivalent:

{
  "name": "CI Pipeline",
  "on": {
    "push": {
      "branches": ["main", "develop"]
    },
    "pull_request": {
      "branches": ["main"]
    }
  },
  "jobs": {
    "test": {
      "runs-on": "ubuntu-latest",
      "strategy": {
        "matrix": {
          "node-version": [18, 20, 22]
        }
      },
      "steps": [
        { "uses": "actions/checkout@v4" },
        {
          "name": "Setup Node.js",
          "uses": "actions/setup-node@v4",
          "with": {
            "node-version": "${{ matrix.node-version }}",
            "cache": "npm"
          }
        },
        { "run": "npm ci" },
        { "run": "npm test" },
        { "run": "npm run build" }
      ]
    }
  }
}

Important conversion notes:

• The on key is a YAML boolean problem: in YAML 1.1, bare on is parsed as true. GitHub Actions handles this specially, but generic parsers may trip on it. In JSON, "on" is unambiguous.
• Expression syntax (${{ }}) must be preserved as literal strings in both formats.
• Multi-line run commands use YAML's | literal block style, which becomes a single string with \n characters in JSON.
• Matrix strategies are arrays in both formats but are more readable in YAML's list syntax.

GitHub Actions only reads YAML files, but understanding the JSON structure is valuable for workflow generators and linters.