GitHub Actions Workflow Validator

GitHub Actions workflow files have strict YAML structure requirements that aren’t obvious from the documentation. A misplaced runs-on key, a typo in uses:, or an invalid on: trigger silently breaks your pipeline — and you only find out after pushing and waiting for the workflow to fail. This tool validates your workflow YAML locally before you commit.

What Gets Validated

• YAML syntax — Indentation, colons, quotes, duplicate keys
• Workflow structure — Required on and jobs keys, valid top-level fields (name, permissions, env, defaults, concurrency)
• Job configuration — runs-on values, steps structure, needs references to existing jobs
• Step validation — uses action format (owner/repo@ref), run and uses mutual exclusivity, with and env types
• Trigger validation — Valid event names (push, pull_request, workflow_dispatch, etc.), branch/path filter syntax
• Expression syntax — ${{ }} expression brackets are balanced and placed correctly

Common Mistakes Caught

• Using on: push with branches as a string instead of a list
• Missing runs-on in a job definition
• Steps with both uses and run (only one allowed)
• Invalid cron expressions in schedule triggers
• Referencing a job in needs that doesn’t exist
• Using env at the wrong nesting level

How to Use

1. Paste your .github/workflows/*.yml content into the editor
2. The validator checks structure and semantics in real time
3. Errors and warnings appear with line numbers
4. Fix issues before committing to your repository

Why Validate Locally

GitHub only reports workflow syntax errors after you push and the workflow attempts to run. This creates a frustrating feedback loop:

1. Push a commit with a workflow change
2. Wait for GitHub to pick it up
3. See “Invalid workflow file” in the Actions tab
4. Fix the typo, push again
5. Wait again…

Validating locally before committing saves this entire cycle. Catch structural errors, invalid triggers, and missing references in seconds instead of minutes.

Frequently Asked Questions

Does it validate action versions (e.g., actions/checkout@v4)? It checks the format of uses references (owner/repo@ref pattern) but doesn’t verify that the action or version actually exists on GitHub.

Can it validate reusable workflows? Yes. It validates the structure of reusable workflow files including workflow_call trigger inputs and outputs, and workflow_dispatch input definitions.

Does it check if: condition expressions? It validates that expressions use correct ${{ }} syntax. Full expression evaluation (function calls, context access) is available in the GitHub Actions Expression Evaluator.

Can it validate composite actions (action.yml)? Yes. The validator checks action.yml files for composite actions, including inputs, outputs, and runs structure with steps definitions.

Is my workflow file sent to a server? No. All validation runs in your browser. Your workflow configuration stays on your device.