actlint

A Rust CLI that validates GitHub Actions workflow files and action definition files for metadata correctness. It checks schema structure, expression syntax, context availability, and cross-references.

actlint does not lint JavaScript, TypeScript, shell scripts, Dockerfiles, or any source code. Run your own source linters separately.

Installation

cargo install actlint-cli

Quick start

Lint workflows and actions in the current directory:

actlint lint

Lint a specific directory:

actlint lint .github/workflows/

Output as JSON:

actlint lint --format json

Generate a starter configuration file:

actlint init

Rules

Action rules

Rule	Description	Severity
action/name-required	Action must have a name field	error
action/runs-required	Action must have a runs field	error
action/invalid-using	runs.using must be a valid value	error
action/composite-steps-required	Composite action must have at least one step	error
action/js-main-required	JavaScript action must have a main entry point	error
action/docker-image-required	Docker action must have an image field	error
action/invalid-input-type	Input type must be string, boolean, choice, or environment	error
action/choice-requires-options	Choice inputs must define options	error
action/boolean-default-invalid	Boolean input default must be "true" or "false"	error
action/choice-default-not-in-options	Choice default must be one of the defined options	error
action/output-invalid-step-ref	Composite output references a non-existent step ID	error
action/file-not-found	JS action main/pre/post file does not exist on disk	warning
action/docker-image-not-found	Docker image path does not exist on disk	warning
action/invalid-branding-icon	Branding icon is not a valid Feather icon name	error
action/invalid-branding-color	Branding color is not a valid GitHub-supported color	error
action/expression-lex-error	Expression tokenization failed	error
action/expression-parse-error	Expression parsing failed	error
action/expression-check-error	Expression uses an invalid context for its scope	error

Workflow rules

Rule	Description	Severity
workflow/no-jobs	Workflow must have at least one job	error
workflow/invalid-job-id	Job ID is not a valid identifier	error
workflow/missing-runs-on	Job is missing runs-on	warning
workflow/invalid-needs-ref	Job needs references a non-existent job	error
workflow/circular-needs	Circular dependency detected in job needs	error
workflow/step-no-action	Step must have either uses or run	error
workflow/step-uses-and-run	Step cannot have both uses and run	error
workflow/invalid-uses	uses value does not match a valid format	warning
workflow/duplicate-step-id	Duplicate step id within a job	error
workflow/expression-lex-error	Expression tokenization failed	error
workflow/expression-parse-error	Expression parsing failed	error
workflow/expression-check-error	Expression uses an invalid context for its scope	error

Other

Rule	Description	Severity
parse-error	YAML parsing failed	error
io-error	File could not be read	error

Configuration

Create .actlint.yml in your project root (or run actlint init):

# Paths to search for workflow files
workflow_paths:
  - .github/workflows

# Paths to search for action definition files
action_paths:
  - .

# Glob patterns of files to ignore
ignore: []

# Rule overrides
# rules: {}

Override the config file path with --config:

actlint lint --config path/to/.actlint.yml

Output formats

Text (default)

[error] action/name-required: action must have a 'name' field
[error] workflow/no-jobs: workflow must have at least one job

JSON

actlint lint --format json

[{
  "severity": "error",
  "rule": "action/name-required",
  "message": "action must have a 'name' field",
  "offset": 0,
  "help": null
}]

SARIF

actlint lint --format sarif

Produces SARIF v2.1.0 output for integration with GitHub Code Scanning and other SARIF-compatible tools.

Exit codes

Code	Meaning
0	No errors found (warnings are allowed)
1	One or more errors found
2	Tool error (config failure, IO error)

Architecture

actlint is a Cargo workspace with two crates. actlint-core is the library containing YAML parsing (via yaml-rust2 with position tracking), an expression engine (handwritten lexer and recursive-descent parser), context availability checking, and all lint rules. actlint-cli is a thin binary that uses clap for argument parsing and schematic for configuration loading, then delegates to actlint-core for the actual linting.

License

MIT