GitHub ActionsワークフローYAMLのフォーマット

GitHub Actions YAMLフォーマット

GitHub Actionsワークフローは .github/workflows/ に格納されたYAMLファイルで定義されます。これらのファイルはトリガー、ジョブ、ステップ、環境設定を含むCI/CDパイプラインを記述します。GitHub Actionsは YAML構造に厳密なため、一貫したフォーマットは重要です。

ワークフローファイル構造

name: CI Pipeline

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

permissions:
  contents: read

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

  deploy:
    needs: test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to production
        run: |
          echo "Deploying..."
          ./deploy.sh
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}

主要なフォーマットルール

1. トップレベルキー — name、on、permissions、env、jobs はすべてルートレベル
2. ジョブのインデント — ジョブは jobs: の下に2スペースインデントでネスト
3. ステップリスト — 各ステップは steps: キーの下で - で始まる
4. 複数行スクリプト — 複数行の run コマンドにはパイプ（|）演算子を使用
5. 式の構文 — ${{ }} 式をYAML構文と混同しない

よくある間違い

• on: のクォート忘れ — 一部のYAMLパーサーでは on がブール値（true）として解釈される。GitHubはこれを正しく処理するが、他のツールではそうではない場合がある
• 不正確なmatrixインデント — matrix キーは strategy の下に適切にネストされなければならない
• ステップの順序 — uses と run は1つのステップ内で相互排他的
• 複数行コマンドのパイプ欠落 — | がないと run コマンドの改行が折りたたまれる

再利用可能なワークフローとコンポジットアクション

フォーマットは再利用可能なワークフローファイル（workflow_call トリガー）やコンポジットアクション定義（action.yml）にも適用されます。これらは類似のYAML構造に従いますが、トップレベルキーが異なります。