https://github.com/cardinal-cryptography/github-actions-validator
Better syntax check for GitHub Actions
https://github.com/cardinal-cryptography/github-actions-validator
github github-actions
Last synced: 2 months ago
JSON representation
Better syntax check for GitHub Actions
- Host: GitHub
- URL: https://github.com/cardinal-cryptography/github-actions-validator
- Owner: Cardinal-Cryptography
- License: bsd-2-clause
- Created: 2023-02-20T18:07:23.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-03-28T13:59:16.000Z (3 months ago)
- Last Synced: 2025-03-28T14:38:40.251Z (3 months ago)
- Topics: github, github-actions
- Language: Go
- Homepage:
- Size: 3.95 MB
- Stars: 0
- Watchers: 2
- Forks: 3
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# github-actions-validator
[](https://pkg.go.dev/github.com/Cardinal-Cryptography/github-actions-validator) [](https://goreportcard.com/report/github.com/Cardinal-Cryptography/github-actions-validator) 
Quick tool to validate workflows and actions in .github directory
## Checks
See the checks that are performed on all the workflow and action files. These are separate into errors
and warnings. Each check has a code where as one starting with `E` indicates an error, `N` indicates
a warning about invalid naming convention and, finally `W` is any other warning.
Additionally, code will contain either `A` if it is an action where the issue is found, and `W` if
issue occurs in a workflow.
### Errors
| Code | Description |
|------|-------------|
| EA809 | Called step with id '%s' does not exist |
| EA811 | Called step with id '%s' output '%s' does not exist |
| EW203 | Job '%s' has invalid value '%s' in 'needs' field |
| EW201 | Called variable '%s' is invalid |
| EW202 | Called input '%s' does not exist |
| EW203 | Job '%s' has invalid value '%s' in 'needs' field |
| EW801 | Path to external action '%s' is invalid |
| EW802 | Path to local action '%s' is invalid |
| EW803 | Call to non-existing local action '%s' |
| EW804 | Required input '%s' missing for local action '%s' |
| EW805 | Input '%s' does not exist in local action '%s' |
| EW806 | Required input '%s' missing for external action '%s' |
| EW807 | Input '%s' does not exist in external action '%s' |
| EW808 | Call to non-existing external action '%s' |
| EW809 | Called step with id '%s' does not exist |
| EW810 | Called step with id '%s' does not exist |
| EW811 | Called step with id '%s' output '%s' does not exist |
| EW254 | Called variable '%s' does not exist in provided list of available vars (when -z provided) |
| EW255 | Called secret '%s' does not exist in provided list of available secrets (when -s provided) |
### Warnings
| Code | Description |
|------|-------------|
| WW101 | Called env var '%s' not found in global, job or step 'env' block - check it |
| WW201 | Called var '%s' may not need to be in double quotes |
### Naming convention warnings
| Code | Description |
|------|-------------|
| NA101 | Action directory name should contain lowercase alphanumeric characters and hyphens only |
| NA102 | Action file name should have .yml extension |
| NA103 | Action name is empty |
| NA104 | Action description is empty |
| NA301 | Action input name should contain lowercase alphanumeric characters and hyphens only |
| NA302 | Action input must have a description |
| NA501 | Action output name should contain lowercase alphanumeric characters and hyphens only |
| NA502 | Action output must have a description |
| NW101 | Workflow file name should contain alphanumeric characters and hyphens only |
| NW102 | Workflow file name should have .yml extension |
| NW103 | Env variable name '%s' should contain uppercase alphanumeric characters and underscore only |
| NW104 | Workflow name is empty |
| NW106 | When workflow has only one job, it should be named 'main' |
| NW107 | Called variable name '%s' should contain uppercase alphanumeric characters and underscore only |
| NW301 | Workflow input name should contain lowercase alphanumeric characters and hyphens only |
| NW302 | Workflow input must have a description |
| NW501 | Workflow job name should contain lowercase alphanumeric characters and hyphens only |
| NW502 | Env variable name '%s' should contain uppercase alphanumeric characters and underscore only |
| NW701 | Env variable name '%s' should contain uppercase alphanumeric characters and underscore only |
## Building
Run `go build -o github-actions-validator` to compile the binary.
### Building docker image
To build the docker image, use the following command.
docker build -t github-actions-validator .
## Running
Check below help message for `validate` command:
Usage: github-actions-validator validate [FLAGS]
Runs the validation on files from a specified directory
Required flags:
-p, --path Path to .github directory
Optional flags:
-s, --secrets-file Check if secret names exist in this file (one per line)
-z, --vars-file Check if variable names exist in this file (one per line)
Use `-p` argument to point to `.github` directories. The tool will search for any actions in the `actions`
directory, where each action is in its own sub-directory and its filename is either `action.yaml` or
`action.yml`. And, it will search for workflows' `*.yml` and `*.yaml` files in `workflows` directory.
Additionally, all the variable names (meaning `${{ var.NAME }}`) as well as secrets (`${{ secret.NAME }}`)
in the workflow can be checked against a list of possible names. Use `-z` and `-s` arguments with paths
to files containing a list of possible variable or secret names, with names being separated by new line or
space.
### Example of checking secrets
% cat ~/secrets-list.txt
MY_SECRET_1
MY_SECRET_2
% ./github-actions-validator validate -p /path/to/.github -s ~/secrets-list.txt | grep '^EW25'
EW255: workflow my-workflow.yml Called secret 'GITHUB_TOKEN' does not exist in provided list of available secrets
### Using docker image
Note that the image has to be present, either built or pulled from the registry.
Replace path to the .github directory.
docker run --rm --name tmp-gha-validator \
-v /Users/me/my-repo/.github:/dot-github \
github-actions-validator \
validate -p /dot-github
## Exit code
Currently, tool always exit with code 0. To check if there are any errors, please use `grep` to filter
the output for errors.