Common YAML Mistakes in Actions Files
GitHub Actions workflows are YAML files with a specific schema, and YAML's flexibility makes it easy to write something syntactically valid that is semantically wrong.
The `on: true` gotcha: YAML interprets bare on as the boolean true in some parsers. Always quote it: "on": or use the full form. This is the most common beginner mistake.
Missing `runs-on`: every job requires a runs-on key specifying the runner. Omitting it produces a validation error that only appears when the workflow runs.
Steps without `run` or `uses`: a step must do something — either run a shell command (run:) or invoke an action (uses:). An empty step or a step with only a name: fails at runtime.
Incorrect indentation: YAML is whitespace-sensitive. A two-space indentation error can move a key to a different nesting level without producing a parse error, just wrong behavior.
Validating Locally
A workflow validator parses the YAML and checks it against the Actions schema without requiring a push. It catches structural errors, unknown keys, and common pitfalls before they consume CI minutes.
Other Things to Check
secretsreferences must match secrets defined in the repository or organization settings.needs:job dependencies must reference jobs that actually exist in the workflow.if:conditions use the Actions expression syntax, not standard YAML or JavaScript.
Validate every workflow change before pushing to avoid broken CI pipelines.