GitHub Actions Workflow Validator

GitHub only tells you that a workflow is broken after you push it, and then often with a single line such as Invalid workflow file. This validator parses the YAML and checks the structure against the workflow syntax: the top-level keys, on with its event names and filters, and for every job runs-on and steps — or uses for a job that calls a reusable workflow. Every step must have exactly one of uses and run; shell and working-directory need run, with needs uses. Misspelled keys such as runs_on get a suggestion.

Relations are checked too. needs must name jobs that exist and must not form a cycle. Job and step ids must start with a letter or _ and contain only letters, digits, - and _. uses must have the form owner/repo@ref, ./local/path or docker://image. Cron expressions in on.schedule need five valid fields. permissions must use known scopes with read, write or none. timeout-minutes must be a number, and every ${{ needs its }}.

Security findings are warnings and notes, not errors: an action that follows a branch (@main) runs whatever is pushed there, a third-party action pinned to a tag can be moved by its owner, and only a full commit SHA is immutable. A workflow without permissions gives the GITHUB_TOKEN the defaults of the repository. The validator does not contact GitHub: it cannot know whether an action, a version, a runner label or a secret exists, and it does not evaluate expressions. The key on is read as the string it is meant to be; generic YAML 1.1 tools turn it into the boolean true, which is why some YAML linters complain about workflows.