Format GitHub Actions Workflow YAML

GitHub Actions YAML Formatting

GitHub Actions workflows are defined in YAML files stored in .github/workflows/. These files describe CI/CD pipelines with triggers, jobs, steps, and environment configurations. Consistent formatting is critical because GitHub Actions is strict about YAML structure.

Workflow File Structure

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

Key Formatting Rules

1. Top-level keys — name, on, permissions, env, jobs are all at the root level
2. Job indentation — Jobs are nested under jobs: with 2-space indentation
3. Steps list — Each step starts with - under the steps: key
4. Multi-line scripts — Use the pipe (|) operator for multi-line run commands
5. Expression syntax — ${{ }} expressions must not be confused with YAML syntax

Common Mistakes

• Forgetting to quote on: — In some YAML parsers, on is interpreted as a boolean (true). GitHub handles this correctly, but other tools may not
• Incorrect matrix indentation — The matrix key must be properly nested under strategy
• Step ordering — uses and run are mutually exclusive within a single step
• Missing pipe for multi-line commands — Without |, line breaks in run commands are collapsed

Reusable Workflows and Composite Actions

Formatting also applies to reusable workflow files (workflow_call trigger) and composite action definitions (action.yml). These follow similar YAML structure but with different top-level keys.