Skip to content
forked from rhysd/actionlint

About

Find problems in your GitHub Actions workflows

Topics

Resources

Contributing

Security policy

Stars

64 stars

Watchers

0 watching

Forks

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace
 
 

Latest commit

 

History

3,411 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

actionlint

CI Status Latest release NPM Version PyPI version pkg.pr.new Docker latest Docker nightly Sponsor this project

UPCOMING — actionlint v2. Try the master preview.

Catch the broken workflow before the runner does.

actionlint checks GitHub Actions workflows, action manifests, and the scripts inside them. Find the misspelled matrix property, the missing action input, the unsafe interpolation, and the shell bug before the next push.

Watch actionlint check workflows, scripts, and action metadata

Try the playground · Install · Browse the rules · Watch the video

v2 brings Cargo-style diagnostics, WebAssembly plugins, ShellCheck and Ruff, action discovery, a language server, source fixes, and structured reports into the same checker.

One command checks workflows, actions, and scripts

actionlint check

Run it in a Git repository. actionlint discovers workflows and action.yml or action.yaml manifests, including local actions that no workflow references. It follows local action and reusable-workflow dependencies and checks scripts inside composite actions.

What you wrote What actionlint checks
${{ matrix.platform }} Whether platform exists and its value has the expected type.
needs: [build] Whether the job exists and the dependency graph contains a cycle.
uses: ./actions/deploy The action's metadata, required inputs, declared outputs, and composite steps.
A reusable-workflow call Inputs, secrets, outputs, and declared permission constraints.
run: ... ShellCheck findings in shell scripts and Ruff findings in Python scripts.
${{ github.event.issue.title }} inside a script Whether untrusted text is inserted into executable script text.
A cache write on an untrusted event Whether the workflow's event guards and cache permissions allow unsafe access.
runs-on, trigger filters, or a schedule Runner compatibility, glob syntax, cron expressions, and IANA timezones.

Findings include source locations, highlighted ranges, explanations, and related locations where available. The check examples show what each check catches.

See the mistake before you push it

This workflow defines matrix.os, then asks for matrix.platform. Save it as .github/workflows/ci.yml and run actionlint check --output-format=pretty .github/workflows/ci.yml. The Cargo-style report shows the rule name, source location, and failing expression:

name: CI
on: push
permissions: {}
jobs:
  test:
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
    runs-on: ${{ matrix.platform }}
    steps:
      - run: echo "Testing"
error[expression-reference] unknown-property
  property "platform" is not defined in matrix
  --> .github/workflows/ci.yml:9:18
  |
9 |     runs-on: ${{ matrix.platform }}
  |                  ^^^^^^^^^^^^^^^
  = config: lint.rules.correctness.expression-reference

Change matrix.platform to matrix.os, check again, and both runner names pass. Other findings can include explanations, related locations, documentation links, and available fixes in the same report.

actionlint also checks expression contexts, action inputs, job outputs, matrix filtering, YAML anchors, and composite-action scripts. It can report errors at the expression that failed, including inside multiline YAML values.

GitHub Actions features GitHub doesn't even know about

Build an action's inputs with ${{ insert }}:

with:
  ${{ insert }}: >-
    ${{ fromJSON('{"fetch-depth": 0, "persist-credentials": false}') }}

actionlint checks the inserted input names and values, even when you build them from matrix expressions. You can insert environment variables into env: the same way.

Use the weird parts of GitHub Actions

Comments inside JSON? Unquoted keys? Trailing text after the closing brace? Mixed-case function names? GitHub accepts them. actionlint understands them.

The actions-rs CI workflow puts all of that through fromJSON(), toJSON(), and fromJSON() again:

runs-on: ${{ matrix.os }}
strategy:
  matrix: |-
    ${{
      FrOmJsOn(
        tOjSoN(
          fRoMjSoN(
            '{
              // load-bearing newline
              os:
              [
                ''ubuntu-latest'',
                "windows-latest"
                ,''macos-latest'',
              ],
              octal: [010], hex: ["0xFF"]
              /*,array_hole: [,]*/ , empty_string: [""]
              ,null_value: [null],undefined_value: ["undefined"],
              not_a_number: ["NaN"], positive_infinity: ["Infinity"]
              ,constructor: ["new Date()"],
            }
            this trailing sentence is apparently fine'
          )
        )
      )
    }}

actionlint resolves the matrix and reports the loose JSON as information. That workflow also runs YAML-anchored actions in parallel: and Rust scripts through actions-shell cargo-script {0}, with Cargo dependencies declared inside run:.

actionlint still catches its mistakes. if: ${{ format('{0}', false) }} produces the string "false", so the job runs. And ${{ github.workspace }} inside a TOML string can break the Rust script's dependency declaration if the path contains an apostrophe.

Build action inputs with JSON comments, unquoted keys, and trailing commas

The kp2bw Windows workflow builds action inputs for npm, Bun, Bitwarden, and Vaultwarden in one expression. Yes, fromjsOn() works too:

strategy:
  matrix:
    pm: [npm, bun]
    cli: [bw, vw]
    include:
      - ${{ fromJSON('[/* npm ships inside nodejs */ {pm:''bun'', tools:''bun''},] that is all, folks') }}
steps:
  - uses: jdx/mise-action@6612f0ef07ed2a736cd1e00a94a065522dd41195
    with:
      ${{ insert }}: ${{ fromjsOn(format('{{install_args:''{0}'' /* npm ships inside nodejs */,}} that is all, folks', join(fromJSON(format('[''nodejs'',''uv'',''python'',{0},] // bun, if you insist', toJSON(matrix.tools))), ' '))) }}

actionlint checks all four combinations. It computes install_args for each one, including the extra bun for Bun, and checks the resulting action inputs.

The shellcheck-rs wiki fixture also uses ${{ insert }} in env:, expression-valued with: mappings, and YAML aliases for action references. The expression behavior guide explains the runner comparisons behind these checks, including why '017' == 17 and fromJSON('017') == 15 can both be true.

ShellCheck and Ruff belong in the same report

For a project without configuration, initialize it once:

actionlint config init --toml
actionlint check

Initialization installs the default ShellCheck and Ruff WebAssembly plugins and saves their exact versions in .github/actionlint.toml. Commit that file. Local checks, the language server, and CI read the same configuration.

The Rust port of ShellCheck makes its WebAssembly plugin possible. ShellCheck runs inside actionlint and in the browser playground. You do not need native ShellCheck or Ruff executables for these backends. Their findings point back to the original workflow or action file, with GitHub expressions handled by the host before script analysis.

Use Ruff settings to select Python rules and target versions. Use ShellCheck settings and inline directives to control shell diagnostics. Native ShellCheck and Ruff executables are also supported. See script-linter configuration.

Preview the fix, then apply it

actionlint fix
actionlint fix --apply

The first command previews available safe edits as JSON. The second applies them and checks the updated files. actionlint rejects conflicting edits and stale source revisions before writing. Add --include-suggested when you want to review edits that need a judgment call.

Get diagnostics and fixes while you edit

Connect your editor to actionlint's language server over standard input and output:

actionlint lsp

The server checks unsaved buffers, updates diagnostics as you edit, and offers versioned quick fixes and suppression actions. Related locations help trace a finding into the local action or reusable workflow that caused it. Expression completion suggests context properties and event fields. See editor support for supported features and editor setup.

The browser playground runs the language server in a WebAssembly worker. Paste a workflow, edit it, follow diagnostics to their source, and apply available quick fixes in the browser. It includes ShellCheck for embedded shell scripts and uses the language server for expression completion.

Check the actions your workflow calls

Remote action metadata gives the checker declared inputs, outputs, and runtimes. Remote reusable-workflow metadata adds input, secret, output, and permission checks across calls.

The bundled Commitish WebAssembly plugin resolves branches, tags and commit IDs. Actionlint fetches the metadata at the selected commit. Cache dependencies before working offline:

actionlint cache warm .github/workflows
actionlint check --offline .github/workflows

Metadata reports distinguish unavailable data from invalid declarations. An optional resolver can also propose immutable commit pins for review. Read remote dependency checks for resolution, caching, and authentication.

Configure rules in TOML, with editor completion

Use TOML for configuration. Add rule settings to the generated .github/actionlint.toml, keeping its pinned plugin declarations:

#:schema https://cdn.jsdelivr.net/gh/kjanat/actionlint@2/actionlint.schema.json

[lint.rules]
preset                            = "recommended"
security                          = "error"
suspicious.mixed-type-comparisons = "error"
conventions.job-timeout           = { level = "error", options = { max-minutes = 30 } }

[[overrides]]
includes                                   = [".github/workflows/legacy.yml"]
lint.rules.correctness.deprecated-commands = "off"

We recommend Tombi for your editor's TOML language server. The schema directive connects the file to actionlint's settings for validation and completion. You can complete dotted keys, rule levels, and rule options as you write.

The example sets the security category to error, configures two individual rules, and disables one check only for legacy.yml. Rule levels are off, on, info, warn, and error. --strict also respects rules you disable.

The rule catalogue covers correctness, suspicious behavior, security, and conventions. It includes checks for empty triggers and steps, string conditions, mixed-type comparisons, missing permissions, unpinned references, runtime lifecycle, and job timeouts. Each rule describes its purpose, options, and examples.

actionlint rules
actionlint rules matrix
actionlint check --strict

YAML, JSON, and JSONC configurations are also supported. Use extends to share local or HTTPS configuration files. Declare self-hosted runners, known variables and secrets, and repository permission defaults separately from lint rules.

Inspect the effective settings and their sources:

actionlint config show --origin
actionlint config validate
actionlint doctor

For an existing configuration, preview and apply its migration:

actionlint config migrate
actionlint config migrate --write

Review and commit the changes. See configuration, the rule reference, and the migration guide.

Add your own checks

WebAssembly plugins can analyze documents, check embedded languages, or provide runner inventory. A plugin can return diagnostics and source edits with its own rule metadata and configuration schema.

actionlint plugin search shellcheck
actionlint plugin list
actionlint plugin sync
actionlint plugin update

Search finds available plugins. Sync restores the exact configured versions. Update resolves newer releases explicitly. Normal checking restores missing pinned artifacts without upgrading the project.

You can load local artifacts, install registry releases, or pin directly hosted artifacts by SHA-256. actionlint verifies downloaded bytes and applies execution limits. Use actionlint plugin inspect to read artifact metadata without executing the plugin.

The plugin guide includes SDKs, Rust, C, and TinyGo examples, process-provider manifests, and custom script-linter integrations.

Send results where you work

The Cargo-style terminal report shows source excerpts, range indicators, related locations, and available fixes. Select another format for CI or your own tools:

actionlint check --json
actionlint check --output-format=jsonl
actionlint check --output-format=github
actionlint check --output-format=sarif --output-file=actionlint.sarif

You can emit multiple formats from one analysis, use custom templates, or read typed JSON with its published schema and TypeScript definitions. JSON includes diagnostic ranges, rule metadata, source references, related locations, and structured workflow and action documents.

The v2 GitHub Action runs the native binary through a Node launcher. It supports annotations, job summaries, verified plugin caching, report files, optional SARIF output, and optional pull-request reviews. It can also install a selected binary version without running checks.

Use the Action guide for setup and available release versions. The integration guide covers pre-commit, native Git hooks, reviewdog, and editors. See result formats before building a report consumer.

Get actionlint

The installation guide covers Windows, macOS, Linux, npm, PyPI, Docker, and other package managers.

Try the latest preview from master:

npx https://pkg.pr.new/kjanat/actionlint/@kjanat/actionlint@master

Or build from source with Go 1.27 or newer:

go install ./cmd/actionlint

Add Go's installation directory to PATH and keep git available for repository discovery. Then check a repository, selected files, or a directory:

actionlint check
actionlint check .github/workflows/ci.yml .github/actions/build/action.yml
actionlint check .github/

Discovery respects Git ignore rules and configured file filters. Use --no-ignore to include excluded files. Findings produce a nonzero exit status. See usage for globs, stdin, output options, and shell completion.

The v2 migration notes cover plugin dependencies, pre-commit, and result-format changes.

Build and contribute

Read the contributing guide, then use the project tools through mise:

mise exec -- runner install
mise exec -- go build ./cmd/actionlint
mise exec -- run test
mise exec -- run fmt

The repository layout explains where the checker, CLI, plugins, and applications live. Open an issue with a workflow that reproduces a bug or describes a check you need.

License

actionlint uses the MIT license. The identity artwork is by Kaj Kowalski and licensed under CC BY 4.0.

Support development.

About

Find problems in your GitHub Actions workflows

Topics

Resources

Contributing

Security policy

Stars

64 stars

Watchers

0 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages