GitHub Actions Workflow Syntax Guide
Learn the complete syntax for GitHub Actions workflow YAML files. Use the validator above to check your workflows for errors, then reference this guide to fix them. All processing runs in your browser.
GitHub Actions YAML Validator
Validate GitHub Actions workflow files for syntax errors, missing fields, deprecated actions, broken job dependencies, and common misconfigurations. Runs entirely in your browser.
About GitHub Actions Workflow Validation
GitHub Actions workflows are YAML files in .github/workflows/ that define CI/CD automation — building, testing, deploying, and more.
What we check:
- Required fields — on (triggers), jobs, runs-on, steps
- Trigger validation — event names, cron schedules, workflow_dispatch inputs
- Job structure — runs-on, needs dependencies, timeout, strategy/matrix
- Step validation — uses vs run, action version pinning, id uniqueness
- Deprecated actions — flags outdated action versions with upgrade suggestions
- Permissions — validates permission scopes and values
- Expression syntax — unclosed ${{ }} expressions
- Reusable workflows — validates uses/steps exclusivity
- Best practices — timeouts, concurrency groups, naming
Everything runs in your browser — no data is sent over the network.
Workflow file structure
Every GitHub Actions workflow requires a YAML file in .github/workflows/ with at minimum two fields: 'on' (trigger events) and 'jobs' (the work to execute). Optional top-level fields include 'name' (display name in the UI), 'permissions' (GITHUB_TOKEN scopes), 'env' (global environment variables), 'concurrency' (prevents duplicate runs), and 'defaults' (shared step settings like shell and working-directory).
name: CI
on:
push:
branches: [main]
pull_request:
permissions:
contents: read
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm ci && npm testTrigger events and filters
The 'on' field accepts a single event string, an array, or a mapping with filters. Common triggers: push and pull_request with branch/path filters, schedule with cron syntax, workflow_dispatch for manual triggers with inputs, and workflow_call for reusable workflows. Filter examples: branches, branches-ignore, paths, paths-ignore, tags, and types (opened, synchronize, closed for pull_request).
on:
push:
branches: [main, 'release/**']
paths:
- 'src/**'
- '!src/**/*.test.ts'
pull_request:
types: [opened, synchronize]
schedule:
- cron: '0 9 * * 1' # Every Monday at 9 AM
workflow_dispatch:
inputs:
environment:
type: choice
options: [staging, production]Jobs and steps
Each job runs on a fresh runner VM specified by runs-on. Jobs run in parallel by default — use 'needs' to create dependencies. Each job contains steps that run sequentially. Steps use either 'uses' (to call an action) or 'run' (to execute shell commands). Steps can have 'id' for referencing outputs, 'if' for conditional execution, 'with' for action inputs, and 'env' for environment variables.
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
node: [18, 20, 22]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node }}
- run: npm ci
- run: npm test
deploy:
needs: test
runs-on: ubuntu-latest
if: github.ref == 'refs/heads/main'
steps:
- run: echo 'Deploying...'Frequently Asked Questions
What is the minimum required structure for a GitHub Actions workflow?
A valid workflow needs 'on' (at least one trigger event) and 'jobs' (at least one job with runs-on and steps). The 'name' field is optional but recommended. Each step needs either 'uses' or 'run'.
How do I run jobs in sequence instead of parallel?
Add 'needs: job-id' to dependent jobs. For example, 'deploy' with 'needs: [build, test]' waits for both to complete. Without 'needs', all jobs start simultaneously.
What runners are available for GitHub Actions?
GitHub-hosted runners include ubuntu-latest, ubuntu-24.04, ubuntu-22.04, windows-latest, windows-2022, macos-latest, macos-15, macos-14, and macos-13. You can also use self-hosted runners for custom environments.
Related Inspect Tools
LLM Token Counter
Count tokens and estimate API costs for GPT-4o, Claude, Gemini, and other LLMs with BPE tokenization
AI Model Comparison
Compare 23 AI models (Claude 4.6, GPT-4.1, Gemini 3) + 5 coding IDEs (Cursor, Copilot, Windsurf, Kiro, Antigravity) — pricing, context windows, capabilities
JSON Visualizer
Visualize JSON as an interactive tree — collapsible nodes, search, path copy, depth controls, and data statistics
Git Diff Viewer
Paste unified diff output from git diff and view it with syntax highlighting, line numbers, and side-by-side or inline display