| name | ansible-verification-loop |
| description | Reviews and modifies Ansible roles, collections, playbooks, and tasks, verified through the target repository's own lint/test loop rather than declaring success from the edit alone. Use when reviewing or modifying any Ansible role, collection, playbook, or task. |
ansible-verification-loop
Purpose
Provide a structured approach for reviewing and modifying Ansible roles and collections. Ensures
changes are made consistently with the target repo's own conventions, verified through a real
lint/test loop, and reported clearly. It works across different repos' test setups (molecule,
ansible-test, tox, pytest-ansible, etc.) by discovering what is actually there rather than assuming
one project's layout.
Reference
- YAML 1.2.2 Specification โ authoritative reference for scalar
resolution, quoting, and tag semantics. Use it to explain why a value needs quoting, e.g. the
"Norway problem" (unquoted
no/yes/on/off/y/n resolving to booleans) or numbers with
leading zeros/colons resolving to octal/sexagesimal. Ansible's YAML loader and ansible-lint's
default yaml/truthy rule already reject unquoted truthy values other than true/false, so
this reinforces existing lint behavior โ never use the spec to justify removing existing
quoting, the --- document-start marker, or any other convention ansible-lint/yamllint
already enforces in the target repo.
When to use this
- Reviewing or modifying any Ansible role, collection, playbook, or task.
- You need to ensure changes are consistent with existing conventions and actually verified before
being reported done.
When NOT to use this
- Changes that do not involve Ansible roles, collections, playbooks, or tasks.
Steps
- Orient in the target role/collection before changing anything:
- Read the relevant role's
defaults/main.yml, tasks/main.yml, meta/main.yml, and any
handlers/, vars/, templates/ it touches.
- For collections, also check
galaxy.yml, meta/runtime.yml, and requirements.yml for
dependencies and supported Ansible/Python versions.
- Discover and follow the repo's own authoritative rules. Check for (roughly in priority order):
.github/copilot-instructions.md, .github/instructions/*.instructions.md, CONTRIBUTING.md,
CLAUDE.md, AGENTS.md, or a docs/ style guide. If none exist, infer conventions from
surrounding code (FQCN vs short module names, quoting style, variable naming, indentation).
Regardless of what a repo's docs say, treat SSH/sudo/PAM/audit/SELinux/AppArmor/firewall/
mounts/sysctl/services/auth-adjacent tasks as high-sensitivity.
- Follow the existing conventions and patterns already in the codebase: naming, file structure,
style.
- If OS-conditional logic changes, keep
meta/main.yml galaxy_info.platforms (role) or the
collection's declared platform support in sync with it.
- If default values, argument specs, or variable names change, update all relevant documentation
(README, role docs,
meta/argument_specs.yml, etc).
- Add or update test coverage for the change. Discover how this repo actually tests roles before
assuming a layout. Common patterns, roughly in order of how likely you are to find them:
- Molecule scenarios per role (
roles/<name>/molecule/<scenario>/).
- A shared/centralized molecule setup exercising multiple roles together (e.g. one
converge.yml that includes several roles plus per-role verify_<role>.yml files included
from a shared verify.yml). If you find this pattern, add/update the entries for the role
you touched rather than creating a new scenario.
ansible-test (collections): unit tests under tests/unit/, integration targets under
tests/integration/targets/.- Plain
tox envs wrapping any of the above. Check tox.ini for the actual env names before
assuming what tox -e <name> runs.
Match whatever pattern the repo already uses; do not introduce a new test framework alongside an
existing one.
- Verify the change (see checklist below). If issues are found, fix them and re-verify. Repeat
until all issues are resolved or verification has been attempted 3 times, whichever comes
first. If issues remain unresolved after 3 attempts, stop and report to the user instead of
proceeding or silently giving up.
- Report any issues found during verification, with detailed reproduction steps and relevant
logs/output.
Verify
- Run
ansible-lint (or the repo's configured linter/config, e.g. a non-default .ansible-lint
path) and confirm a clean exit / expected output. This is the primary quality gate. Do not add
suppressions to silence findings from new changes just to get a clean run.
- Run the repo's full test entry point and confirm success. This is usually a
tox env (check
tox.ini / tox -av for the right one, e.g. tox -e docker, tox -e molecule), a Makefile
target, or a CI workflow file (.github/workflows/*.yml) that spells out the exact commands.
It typically installs dependencies (requirements.yml/galaxy.yml), lints, then converges and
verifies in containers/VMs across the platforms the role/collection claims to support, including
an idempotence check.
- If invoking
molecule test / ansible-test directly instead of through the repo's wrapper, do
first what the wrapper would have done for you: install requirements.yml, and always run
ansible-lint as its own separate step. Molecule's own lint subcommand was removed in Molecule
6.x and has not returned, so no version of a direct molecule test/molecule converge invocation
lints for you; skipping the separate ansible-lint run silently drops the primary quality gate.
- While iterating on a single role, use
molecule converge / molecule verify (or the equivalent
faster subcommands for whatever framework is in use) instead of the full test cycle to save
time, but always finish with a full test run before declaring the change verified.
Verification checklist
Never declare this done based on the edit alone. Confirm each of the following:
