ansible-static-lint

A fast, offline static companion to ansible-lint, for editor-on-save, pre-commit, or a CI pre-check. No Ansible runtime, no Python, no environment setup, near-instant feedback. The command is astl.

Same config file. Same rule ids. Same # noqa comments. Same output.

astl is a Go reimplementation of the ansible-lint rules that can be decided from the YAML source alone: 39 of the 51 default rules, reproducing ansible-lint's -f pep8 output byte for byte within that scope. It is not a drop-in replacement for ansible-lint and does not try to become one: keep ansible-lint where its runtime matters, for syntax check, collection resolution, schema validation and --fix.

Try it on your repository

Download the binary. No Go, no Python, no Ansible:

VERSION=0.6.0
OS=$(uname -s | tr 'A-Z' 'a-z')
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
curl -sSfL "https://github.com/arhuman/ansible-static-lint/releases/download/v${VERSION}/ansible-static-lint_${VERSION}_${OS}_${ARCH}.tar.gz" | tar -xz astl
./astl path/to/playbooks

Linux, macOS and Windows, amd64 and arm64, are on the releases page. Each release ships checksums signed with cosign; see docs/supply-chain.md to verify one.

From PyPI, if you already manage ansible-lint with pip or pipx:

pipx install ansible-static-lint
astl path/to/playbooks

The wheel carries the same binary as the release archive above, so there is still no Python at runtime: no interpreter starts when you run astl. Python is only the delivery mechanism. pip install ansible-static-lint works too, in a virtualenv.

In GitHub Actions. Two lines, and the action fetches and checksum-verifies the binary for you:

      - uses: actions/checkout@v7
      - uses: arhuman/ansible-static-lint@v0.6.0

As a pre-commit hook. pre-commit installs astl in an isolated environment and caches it. With pre-commit 3.0 or newer, neither astl nor Go needs to be installed beforehand: language: golang bootstraps the toolchain itself. The first run downloads Go and compiles astl once; every run after that uses the cached binary.

repos:
  - repo: https://github.com/arhuman/ansible-static-lint
    rev: v0.6.0
    hooks:
      - id: astl

With Go already installed, skip the download: go install github.com/arhuman/ansible-static-lint/cmd/astl@latest. Go 1.26 or newer.

None of these ask you to change your repository. If it already has an ansible-lint config file, astl reads it as is: profile, skip_list, enable_list, warn_list and exclude_paths work unchanged, and so do your existing # noqa comments. More in docs/configuration.md.

Why static?

astl has no Ansible runtime and never shells out. It therefore does not:

• run ansible-playbook --syntax-check;
• resolve collections, roles or module argument specs;
• evaluate Jinja templates;
• validate content against JSON schemas;
• apply --fix transforms;
• load custom rule plugins or profiles.

That is the trade-off: astl handles every check that can be decided from the source alone and leaves runtime-dependent validation to ansible-lint. The boundary is measured, not rhetorical: 99% of the corpus findings astl does not report require capabilities it deliberately does not have, and the full per-rule accounting is in docs/scope.md.

The flip side of having no runtime: astl keeps linting files whose references Ansible cannot resolve, where ansible-lint abandons the file and reports only the load failure.

Compatibility

Two numbers, and they measure different things:

Within its scope, astl agrees with ansible-lint on every finding: same file, same line, same column, same message, byte for byte. It also emits 46 findings ansible-lint does not, all on files ansible-lint abandons because its embedded runtime rejects them. Those extras are pinned line for line as an exact set: the harness fails if the set changes in either direction, so a new false positive cannot hide among them.

The corpus, the frozen golden output, and the assertion live in a separate repository, astl-compatibility-check, kept as a sibling directory. It is licensed GPL-3.0-or-later because it contains ansible-lint test data. astl carries neither the corpus nor the golden output into its own tree and stays MIT. What astl does carry, under its default output mode, is ansible-lint's diagnostic message text itself, reproduced verbatim for compatibility; see ADR 0004 for the reasoning and its limits.

How fast?

Measured on Apple Silicon macOS against ansible-lint 26.8.0 (Python 3.14, --offline), on ansible-lint's own examples corpus:

Read the ratios with care: the comparison is asymmetric, since ansible-lint is also running its syntax-check subprocess and the 12 rules astl excludes. The honest headline numbers are cold start and the single playbook, where the gap is interpreter and import overhead that exists before any rule runs; even ansible-lint --version costs half a second.

make bench fails the build if linting the reference corpus exceeds 150 ms, roughly five times the current time, so the property is guarded rather than assumed. Why the numbers look like this is in docs/performance.md.

Using astl in CI

astl is not a drop-in replacement for ansible-lint, so the pipeline that gets the most out of it runs both, at different frequencies:

Adopting the fast tier costs no configuration, since --ids upstream is the default. docs/ci.md has the full workflows: action inputs, SARIF upload to GitHub code scanning, and the pre-commit variants.

Usage

astl path/to/playbooks     # pep8 lines on stdout
astl -f sarif .            # SARIF 2.1.0 instead, see docs/sarif.md
astl -c ci.ansible-lint .  # lint against a named config

astl follows include_tasks, import_tasks, include and import_playbook to a fixpoint, so a task list is linted as tasks even when it does not sit under a tasks/ directory. A file reached only through an include is linted; a file reached both by the directory walk and through an include is linted under both kinds, and the duplicate findings that produces are removed. Templated targets such as {{ role_path }}/x.yml are left alone, since resolving them needs the Ansible runtime astl deliberately does not have.

Exit 3 says a file astl was given could not be examined, so there is no result for it. It takes precedence over 2, because a violation is a result you can read while an unchecked file is not, and an exit code is the only place that can say so. docs/exit-codes.md has the details, including what does not count as unchecked.

Rules

38 static rules are supported; the full equivalence table between astl's domain.rule[tag] identifiers and ansible-lint's is in docs/rules.md. internal/rules/ids.go is the single source both taxonomies are derived from.

--ids native switches output to the native vocabulary: both the rule identifier and the message wording, in pep8 and SARIF alike. The default is --ids upstream, which keeps the pep8 output byte for byte identical to ansible-lint's. The SARIF document is not held to that comparison and does not try to match upstream's own SARIF, for the reasons in ADR 0007. It also declares its run's working directory and which rules were enabled for it; see docs/sarif.md.

# default, ansible-lint's identifier and wording
playbooks/demo.yml:11: no-changed-when: Commands should not change things if nothing needs doing.

# --ids native
playbooks/demo.yml:11: task.unguarded-change: This command always reports changed. Add changed_when, or a creates guard.

The native messages state the defect, then the fix. They are original text, never a reworded copy of upstream's, and they stay under 100 characters so that the fix survives truncation in CI annotations and editor panels.

Early feedback wanted

astl is early. I am looking for real-world Ansible repositories to test whether the static-only trade-off is useful outside the compatibility corpus. If you try it, please open an issue with anything surprising: missing findings, extra findings, unsupported workflows, or simply why you would not use it.

Verifying the implementation yourself

From nothing to a verified binary in three commands, needing neither Python, ansible-lint, nor the test corpus:

git clone https://github.com/arhuman/ansible-static-lint
cd ansible-static-lint
make check

make check builds bin/astl, lints the deliberately broken playbook in examples/, and asserts the run against examples/expected.txt. A working build ends on:

==> ./bin/astl examples
examples/playbook.yml:4:3: name[play][/]: All plays should be named.
examples/playbook.yml:6: command-instead-of-shell: Use shell only when shell functionality is required.
examples/playbook.yml:6: name[missing][/]: All tasks should be named.
examples/playbook.yml:6: no-changed-when: Commands should not change things if nothing needs doing.
examples/playbook.yml:7:13: name[casing][/]: All names should start with an uppercase letter.
examples/playbook.yml:7: package-latest: Package installs should not use latest.
examples/playbook.yml:11: risky-file-permissions: File permissions unset or incorrect.
OK: 7 findings, exit code 2, output matches examples/expected.txt

Anything else is a failure with a diff, because a linter that runs and reports nothing looks exactly like a linter that runs and is broken. The findings and the exit code are both asserted, so neither can drift unnoticed. examples/playbook.yml is 11 lines of YAML and trips seven rules across five families, so it also doubles as the shortest tour of what astl catches.

Development

make check    # build + lint examples/, asserted against examples/expected.txt
make test     # go test -race ./...
make cover    # tests with coverage, fails below COVER_MIN
make audit    # coverage gate + go mod verify + golangci-lint + govulncheck
make parity   # pep8 output parity against the frozen ansible-lint corpus
make bench    # both speed guards: noqa shape, then the corpus under 150 ms
make ci       # tidy + audit + check + parity + bench, the gate before any commit
make tidy     # gofmt + go mod tidy

make test cannot see a compatibility regression: it asserts behaviour, not byte-exact output. Anything touching a rule, a message, or a finding's line or column needs make parity, which needs the sibling repository described above. make ci runs both. See CONTRIBUTING.md.

License

MIT, see LICENSE.