GitHub Actions ワークフローYAML構造

GitHub Actionsワークフローは .github/workflows/ 配下のYAMLファイルで定義されます。そのJSON構造を理解することは、ワークフローをプログラムで生成する際やアクション設定のデバッグに役立ちます。

典型的なGitHub Actionsワークフロー：

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

JSON等価物：

{
  "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" }
      ]
    }
  }
}

変換時の重要な注意点：

• on キーはYAMLのブーリアン問題を引き起こします：YAML 1.1では裸の on は true として解析されます。GitHub Actionsはこれを特別に処理しますが、汎用パーサーは問題が起きる可能性があります。JSONでは "on" は曖昧さがありません。
• 式構文（${{ }}）は両形式でリテラル文字列として保持する必要があります。
• 複数行の run コマンドはYAMLの | リテラルブロックスタイルを使用し、JSONでは \n 文字を含む単一の文字列になります。
• マトリックス戦略は両形式で配列ですが、YAMLのリスト構文の方が読みやすくなります。

GitHub ActionsはYAMLファイルのみを読み取りますが、ワークフロージェネレーターやリンターにはJSON構造の理解が有用です。