Skip to content

Consolidated from ADR-0013 and ADR-0020 on 2026-05-02 per ADR-0047. Source files retained with deprecation banners at docs/adr/0013-ansible-core-fqcn-requirement.md and docs/adr/0020-ansible-lint-production-profile.md.

PLAT-0009 — Ansible Quality Enforcement: FQCN and ansible-lint Production Profile

Field Value
Status Accepted
Date 2026-04-02
Author Ben Peries
Sources ADR-0013 (FQCN), ADR-0020 (ansible-lint)

Context

Ansible roles were being written and merged without a static analysis gate. During the v0.4 baseline run, 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.

Separately, Ubuntu 25.10 ships ansible-core 2.18+ via pip, and the platform targets ansible-core >= 2.17. Starting with ansible-core 2.17, short module names (e.g., apt, copy, service) are deprecated. ansible-lint with the production profile enforces Fully Qualified Collection Names (FQCN) and fails on short names.

Decision

FQCN requirement (from ADR-0013)

All Ansible tasks in the Archon platform must use Fully Qualified Collection Names.

Short name FQCN
apt ansible.builtin.apt
copy ansible.builtin.copy
service ansible.builtin.service
template ansible.builtin.template
file ansible.builtin.file
lineinfile ansible.builtin.lineinfile
command ansible.builtin.command
shell ansible.builtin.shell
debug ansible.builtin.debug
assert ansible.builtin.assert
setup ansible.builtin.setup

Rationale: - ansible-core 2.17+ deprecates short names — they will be removed in a future major version - FQCN eliminates ambiguity when custom collections are installed alongside ansible.builtin - ansible-lint production profile enforces FQCN — CI pipeline fails without it - Consistent naming makes grep/search reliable across all roles

ansible-lint production profile gate (from ADR-0020)

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

  • 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

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 — 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. Does not enforce coding standards.

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

Consequences

  • All existing roles must be audited and converted to FQCN; new roles must use FQCN from the start
  • 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 reach 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
  • No exceptions — even single-task playbooks use FQCN

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