Skip to content

Deprecated — Consolidated into PLAT-0009 on 2026-05-02 per ADR-0047. This source file is retained as a reference; the canonical content is in PLAT-0009.

ADR-0020: ansible-lint at production profile as Ansible quality gate

Status

Accepted — 2026-04-02

Context

Ansible roles were being written and merged without a static analysis gate. During the v0.4 audit of the common role, running ansible-lint revealed 22 violations in a role that had already been deployed — including a missing module collection (community.general.timezone), 14 FQCN violations, anonymous task names, and incorrect handler capitalisation. None of these were caught by code review alone.

A lightweight, fast static analysis tool is needed that can run on every PR without requiring live infrastructure.

Decision

ansible-lint is the static analysis gate for all Ansible roles and playbooks in archon-platform.

  • Version: 26.4.0 (pinned in .venv)
  • Profile: production — the strictest built-in profile
  • Requirement: 0 failures, 0 warnings before merge
  • Venv: ~/homelab/repos/archon-platform/.venv
  • Run command: ansible-lint roles/<role> from the ansible/ directory

Rules enforced at production profile (relevant to this platform)

Rule Description
fqcn[action-core] All module actions must use FQCN (e.g. ansible.builtin.apt)
name[missing] All tasks must have a name: field
name[casing] Task and handler names must start with an uppercase letter
syntax-check Module/collection must be resolvable — catches missing collections

Required collection

community.general must be installed before running lint: 

ansible-galaxy collection install community.general

Alternatives Considered

yamllint only — Catches formatting errors but not Ansible-specific issues. Does not detect missing collections, non-FQCN modules, or unnamed tasks.

Molecule (integration tests) as the only gate — Molecule is the right tool for verifying runtime behaviour but is too slow and infrastructure-dependent to run on every PR. ansible-lint is complementary, not a replacement.

ansible-playbook --syntax-check — Faster than molecule but less thorough than ansible-lint. Does not enforce coding standards.

No gate — Prior state. Resulted in 22 violations discovered post-merge in the common role alone.

Consequences

  • community.general collection must be present in the lint environment
  • CI pipeline (when added) must install the venv and collection before running lint
  • All existing roles must be brought to production profile compliance before new violations are introduced
  • The ansible.builtin.default stdout callback with result_format: yaml must be used in ansible.cfg — community.general.yaml was removed in community.general 12.0.0

References

  • ansible/ansible.cfg
  • ~/homelab/repos/archon-platform/.venv
  • ansible-lint documentation: https://ansible.readthedocs.io/projects/lint/
  • PR #20: fix: common role Ubuntu 25.10 compatibility (22 violations resolved)
  • PR #21: fix: ansible-core compat and baseline run follow-up