GitHub Actions YAML Validator

YAML syntax and workflow structure fail for different reasons

A workflow can be valid YAML and still be unusable as a GitHub Actions workflow. Triggers, jobs, runners, steps, permissions, action references, and secret handling add another layer of rules on top of YAML parsing.

This validator separates those layers so a malformed document is not reported as the same kind of problem as a missing runner, incomplete step, action-version concern, or permission warning.

Jobs, steps, and triggers need their own structural checks

The review looks at the workflow trigger, job definitions, runner declarations, and whether individual steps contain an action reference or command. Optional checks can also surface unpinned action versions, missing permission declarations, and secret-looking literal values.

These findings are intentionally kept separate from YAML syntax errors. That distinction matters when the file parses correctly but GitHub still rejects or behaves differently from what the author expected.

Permission scope is easier to review when it is explicit

name: CI

on:
  push:
    branches:
      - main

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run build

The explicit contents: read permission makes the token scope visible in the workflow instead of leaving the reader to infer repository or organization defaults. Real workflows may need different permissions; the required scope depends on what their jobs actually do.

Token permissions and secret references need separate attention

GitHub Actions workflows often touch source code, packages, release jobs, deployment keys, and cloud credentials. A clear permissions block and proper secret usage make workflows easier to review and safer to maintain.

Use repository or organization secrets for real values. Avoid writing tokens, passwords, API keys, or private URLs directly in workflow files.

Related Tools