actionlint
GitHub Actions workflow linter — syntax, ${{ }} expressions, needs, runner labels, shellcheck for run
actionlint checks .github/workflows/*.yml files before you push: unknown keys and events, typos in needs, errors in ${{ }} expressions, outdated action versions, unsafe interpolation of untrusted data into scripts. It also runs the scripts from run: through shellcheck (and Python scripts through pyflakes) if those are installed.
Syntax
actionlint [options] # all workflows in the nearest .github/workflows
actionlint [options] file… # specific files
actionlint [options] - # workflow from stdin
Without files, actionlint looks for the repository root (a directory with .git) upward from the current one and checks every *.yml/*.yaml in its .github/workflows.
Options
| Option | What it does |
|---|---|
-shellcheck=path | which shellcheck command to use; -shellcheck= (empty) disables checking run: with shellcheck |
-pyflakes=path | same for pyflakes (steps with shell: python); -pyflakes= disables it |
-ignore 'regex' | hide errors whose text matches the regular expression; can be repeated |
-oneline | one line per error, no code snippet — handy for grep and scripts |
-format 'template' | custom output format (Go template); '{{json .}}' — JSON |
-no-color / -color | disable / force color |
-config-file file | path to the config (default .github/actionlint.yaml) |
-init-config | create a starter .github/actionlint.yaml |
-stdin-filename name | file name to use in messages when reading from stdin |
-verbose / -debug | details: which rules are enabled, what was found |
-version | version |
Exit codes
| Code | Meaning |
|---|---|
0 | no errors |
1 | errors found in workflows |
2 | invalid command-line options |
3 | fatal error: repository not found, invalid -format template |
Reading the output
.github/workflows/ci.yml:10:3: job "test" needs job "biuld" which does not exist in this workflow [job-needs]
|
10 | test:
| ^~~~~
file:line:column: message [rule], followed by a snippet with a pointer. Common rules:
| Rule | About |
|---|---|
syntax-check | unknown or missing key (step instead of steps), YAML doesn't parse |
events | unknown event in on: (pull instead of pull_request), invalid filter |
job-needs | needs pointing to a non-existent job, or a dependency cycle |
expression | error in ${{ }}: non-existent property (matrix.os without a matrix, steps.x without a step with that id), wrong type, untrusted input in run: |
action | wrong with: for a known action, too old a version (actions/setup-node@v1) |
runner-label | unknown label in runs-on (for your own runners — set in the config) |
shellcheck | a shellcheck finding for a script in run: with an SCxxxx code |
pyflakes | a finding for a Python script |
Config .github/actionlint.yaml
self-hosted-runner:
labels: [my-runner, gpu] # your own labels for runs-on
config-variables: null # null — don't check vars.* names
paths:
.github/workflows/**/*.yml:
ignore: ['SC2086'] # ignore messages matching the pattern for these files
Examples
mkdir -p .github/workflows && git init -q
cat > .github/workflows/ci.yml <<'EOF'
name: CI
on:
push:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: echo "hello"
EOF
# check all workflows in the repository
actionlint
# a specific file (works outside a repository too)
actionlint .github/workflows/ci.yml
# without shellcheck and pyflakes — only the workflow structure itself
actionlint -shellcheck= -pyflakes= .github/workflows/ci.yml
# compact, one line per error; count the errors
actionlint -oneline | wc -l
# silence specific findings
actionlint -ignore 'SC2086' -ignore 'potentially untrusted'
# custom format: file, line, rule
actionlint -format '{{range $e := .}}{{$e.Filepath}}:{{$e.Line}} [{{$e.Kind}}]\n{{end}}'
# JSON for processing with jq
actionlint -format '{{json .}}' | jq length
# workflow from stdin with a proper name in messages
cat .github/workflows/ci.yml | actionlint -stdin-filename ci.yml -
Pitfalls
no project was found in any parent directories(code3) — running without arguments outside a Git repository. Rungit initor pass the files explicitly.shellcheckmust be installed, otherwise the rule is silently disabled. Same withpyflakes: the IzzyLab sandbox doesn't have it, and-verboseshowsRule "pyflakes" was disabled. An explicit-shellcheck=/-pyflakes=disables them on purpose.- shellcheck errors come as a single line with a code, like
SC2086:info:1:6: Double quote to prevent globbing…. The line and column after the code are inside therun:script, not the workflow file. ${{ github.event.* }}directly inrun:is not a style issue but a vulnerability. The PR title gets substituted into the shell as is. Pass such values throughenv:and reference them as"$TITLE".- Self-hosted runners.
runs-on: my-runnergiveslabel "my-runner" is unknown. List the labels inself-hosted-runner.labelsin the config instead of silencing the error with-ignore. -formatand newlines.actionlintitself replaces\nin the template with a newline, so write\nright in the template text:…{{$e.Line}}\n{{end}}. The usual Go form{{"\n"}}breaks here withunterminated quoted stringand code3.- Valid syntax ≠ working workflow.
actionlintdoesn't check secrets, runner environment variables or token permissions — a workflow can pass the linter and still fail on GitHub.
See also
shellcheck · github-actions · yamlschema · kubeconform · yq · jq