Better syntax check for GitHub Actions’ YAML files

Use github-actions-validator to catch syntax errors that GitHub does not

May 1, 2023 by Mikolaj Gasior

TL;DR

To ensure you GitHub Actions’ YAML files do not use non-existing inputs or outputs, call actions properly, follow naming conventions and many others, use github-action-validator tool.

Intro

Recently I was assigned a task to tidy up repositories that were heavily using GitHub Actions. The .github directory had loads of YAML files which were not structured in any way, with workflows consisting of same code snippets (steps) being duplicated over and over, and no convention for naming things such as inputs or variables.

I found that it was quite difficult to follow names of inputs, outputs, variables and such. It was tricky because when a workflow was executed, calling non-existing input would not come up as an error but it would be just an empty string (''). Naturally, some of the workflows were very important and responsible for building packages or deploying things. Even though a pull request was required to be approved by 2 people, still we had not spotted misspelled variables etc. Also, having agreed with co-workers on “hyphen-case” for inputs and outputs, and capital “snake-case” for vars and secrets, and so on…

Hence, I wanted a way to automatically check that.

github-actions-validator

I have created a tiny tool in Golang that parses all the action and workflow files in the .github directory, collects all the inputs, steps, variables etc. and validates them.

The tool, along with a long list of errors and warnings that are printed out, can be found on at https://github.com/mikogs/github-actions-validator.

Basically, YAML files are Unmarshalled into structs and there is a bunch of loops and conditions.

Validate your .github directory by downloading the binary from Releases and running like below:

./github-actions-validator validate -p /path/to/.github

Have a butcher’s at README file for more detailed usage, like with checking variables and secrets.