← Full reference

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

OptionWhat it does
-shellcheck=pathwhich shellcheck command to use; -shellcheck= (empty) disables checking run: with shellcheck
-pyflakes=pathsame for pyflakes (steps with shell: python); -pyflakes= disables it
-ignore 'regex'hide errors whose text matches the regular expression; can be repeated
-onelineone line per error, no code snippet — handy for grep and scripts
-format 'template'custom output format (Go template); '{{json .}}' — JSON
-no-color / -colordisable / force color
-config-file filepath to the config (default .github/actionlint.yaml)
-init-configcreate a starter .github/actionlint.yaml
-stdin-filename namefile name to use in messages when reading from stdin
-verbose / -debugdetails: which rules are enabled, what was found
-versionversion

Exit codes

CodeMeaning
0no errors
1errors found in workflows
2invalid command-line options
3fatal 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:

RuleAbout
syntax-checkunknown or missing key (step instead of steps), YAML doesn't parse
eventsunknown event in on: (pull instead of pull_request), invalid filter
job-needsneeds pointing to a non-existent job, or a dependency cycle
expressionerror in ${{ }}: non-existent property (matrix.os without a matrix, steps.x without a step with that id), wrong type, untrusted input in run:
actionwrong with: for a known action, too old a version (actions/setup-node@v1)
runner-labelunknown label in runs-on (for your own runners — set in the config)
shellchecka shellcheck finding for a script in run: with an SCxxxx code
pyflakesa 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 (code 3) — running without arguments outside a Git repository. Run git init or pass the files explicitly.
  • shellcheck must be installed, otherwise the rule is silently disabled. Same with pyflakes: the IzzyLab sandbox doesn't have it, and -verbose shows Rule "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 the run: script, not the workflow file.
  • ${{ github.event.* }} directly in run: is not a style issue but a vulnerability. The PR title gets substituted into the shell as is. Pass such values through env: and reference them as "$TITLE".
  • Self-hosted runners. runs-on: my-runner gives label "my-runner" is unknown. List the labels in self-hosted-runner.labels in the config instead of silencing the error with -ignore.
  • -format and newlines. actionlint itself replaces \n in the template with a newline, so write \n right in the template text: …{{$e.Line}}\n{{end}}. The usual Go form {{"\n"}} breaks here with unterminated quoted string and code 3.
  • Valid syntax ≠ working workflow. actionlint doesn'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