A GitHub Actions workflow can fail before a step runs because of invalid YAML, an unsupported expression, an incorrect matrix, or a permission mismatch. This reusable validation checklist shows how to check workflow structure, dependencies, triggers, secrets, reusable workflows, and runtime assumptions before merging a change.
Overview
Validating a GitHub Actions workflow requires more than sending the file through a generic YAML parser. YAML syntax is only the first layer. GitHub Actions also applies its own workflow schema, expression rules, event configuration, runner labels, permission model, and rules for reusable workflows.
A practical validation process uses several checks in order:
- Parse the YAML and confirm that indentation and data types are valid.
- Check the workflow schema: top-level keys, jobs, steps, triggers, and permissions.
- Review expressions such as
${{ github.ref }}, conditionals, matrix values, and secrets. - Confirm that job dependencies, runner labels, action inputs, and outputs match the intended design.
- Test the workflow on a safe branch or controlled event before relying on it for a release.
A browser-based YAML validator can help find malformed indentation, but it cannot reliably determine whether every GitHub-specific key or action input is valid. Treat a generic validator as a syntax checker, then use repository-level checks and a test run for semantic validation. Avoid pasting secrets, tokens, or private configuration into an online tool.
For event-driven workflows, it is also useful to inspect the payload the workflow receives. The Webhook Testing and Debugging Guide provides a complementary approach for inspecting and replaying event data.
Checklist by scenario
When a workflow will not parse
- Confirm the file is stored under
.github/workflows/and has a YAML extension. - Check indentation. Use spaces consistently and keep child keys aligned with their parent.
- Look for missing colons, unmatched brackets, unclosed quotes, and accidental tabs.
- Quote values that could be interpreted unexpectedly, especially strings beginning with special YAML characters.
- Check whether a value should be a string, list, or mapping. For example,
runs-onnormally receives a runner label or expression, whilestepsis a list. - Review the exact line reported by the parser and the lines immediately above it. YAML errors are frequently caused by an earlier indentation mistake.
When the YAML parses but the workflow is rejected
- Verify that the top-level structure includes the intended
name,on, andjobssections. - Check that every job has a valid
runs-on, unless it calls a reusable workflow instead. - Confirm that each step has an appropriate action reference or
runcommand. - Check action input names against the action's documentation. A syntactically valid input can still be ignored if its name is wrong.
- Review job-level and workflow-level
permissions. Grant only the access the workflow needs, and do not assume a token can write simply because a step requests it. - Check runner labels, operating-system assumptions, shell syntax, and installed tooling.
When an expression or conditional fails
- Confirm that the expression is inside the correct GitHub Actions expression context, commonly written as
${{ ... }}. - Check context names such as
github,env,needs,steps,matrix, andsecrets. - Remember that a value produced by one job is not automatically available to another. Define a job output and reference it through
needs. - Use explicit comparisons for important conditions. Confirm whether a value is a string, Boolean, empty value, or null-like value before relying on truthiness.
- Do not use secrets as a general-purpose debugging output. If a condition depends on a secret, test the logic with a non-sensitive marker where possible.
When adding a matrix job
- Make sure
strategy.matrixis a mapping of dimensions to lists or generated values. - Reference dimensions with
matrix.dimensionand use the exact dimension name. - Check that every matrix value is compatible with the runner, setup action, package manager, and project configuration.
- Use
includefor deliberate exceptions andexcludefor combinations that should not run. - Consider whether a failed combination should cancel the rest of the matrix or whether all combinations should finish for diagnostic purposes.
When using reusable workflows
- Distinguish a job that calls a reusable workflow from a job that contains ordinary
steps; the two structures are not interchangeable. - Match caller inputs and secrets to the reusable workflow's declared interface.
- Check whether permissions need to be declared by the caller, the called workflow, or both.
- Validate the referenced path or revision and test changes to the called workflow as carefully as changes to the caller.
What to double-check
Use this compact example as a structural reference, not as a complete production workflow:
name: Test
on:
push:
branches: [main]
pull_request:
permissions:
contents: read
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
node: [20, 22]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node }}
- run: npm ci
- run: npm test
When reviewing a file like this, check the relationship between each layer. The trigger determines when the workflow starts. The permissions determine what the job can access. The matrix determines how many job variations are created. The steps must work on the selected runner and consume the values produced by the matrix.
For API-heavy workflows, validate generated JSON separately from the workflow file. A JSON Schema validation guide can help distinguish malformed payloads from valid payloads that fail an API contract. If a workflow calls a backend endpoint, the browser-to-backend debugging playbook offers a broader way to trace the request path.
Common validation errors
| Symptom | Likely cause | First check |
|---|---|---|
| Workflow is not recognized | Invalid YAML or location | Parse the file and confirm .github/workflows/ |
| Unexpected value | Unsupported key or wrong nesting | Compare the key with the GitHub Actions schema and its parent |
| Expression error | Wrong context, spelling, or quoting | Inspect the context and the value type |
| Matrix value is empty | Incorrect dimension reference | Compare matrix.* with the declared dimension names |
| Permission denied | Insufficient token permissions | Review the effective permissions settings |
| Action input has no effect | Input name does not match the action | Check the action's documented input names |
Common mistakes
- Relying on a generic YAML validator alone: A parser can confirm syntax but cannot prove that a workflow's events, actions, contexts, and permissions are correct.
- Testing only the happy path: Pull requests, pushes, manual runs, scheduled runs, and reusable-workflow calls can provide different context values. Test the event that matters to the job.
- Assuming job order: Jobs may run independently unless a dependency is declared. Use
needswhen a job consumes another job's result or output. - Confusing step outputs with environment variables: A value written by one step needs the correct output or environment mechanism before another step can consume it.
- Hard-coding a runner assumption: Shell commands, file paths, preinstalled software, and permissions can differ between runner environments.
- Debugging by printing secrets: Use safe markers, controlled test values, and masked logs. Never make a credential visible merely to confirm that it exists.
- Changing several workflow concerns at once: Separate trigger, permissions, matrix, and action upgrades when possible. Smaller changes make failed runs easier to diagnose.
When to revisit
Run this checklist before merging every meaningful workflow change, especially when adding a trigger, changing a runner, upgrading an action, introducing a matrix, modifying permissions, or moving logic into a reusable workflow. Revisit it after a failed run whose error message seems unrelated to the edited step; the underlying problem may be configuration or context.
It is also worth reviewing workflow validation before seasonal planning cycles, release preparation, dependency upgrades, and repository-wide CI maintenance. Tool behavior, action interfaces, runner labels, and platform features can change, so confirm important assumptions against the current documentation rather than copying an old configuration indefinitely.
Pre-commit checklist:
- Parse the YAML locally or with a trusted validator.
- Check workflow location, top-level keys, indentation, and data types.
- Review triggers and verify that the intended event supplies the required context.
- Check job dependencies, outputs, runner labels, matrix dimensions, and action inputs.
- Review permissions and remove access the workflow does not need.
- Confirm secrets are passed through the intended interface and never exposed in logs.
- Test the changed workflow on a safe branch or controlled event.
- Record any intentional platform or runner assumptions in comments or repository documentation.
Keeping this checklist beside the workflow review process turns validation into a repeatable developer productivity task rather than a last-minute response to a failed CI run.