ansible-playbook-style

Ansible Playbook Style Contract

Dependencies

• For role composition and directory structure, see ansible-role.mdc which applies these task conventions inside roles.

Naming Conventions

• Start every name field — plays, tasks, handlers, and blocks — with a gerund verb.
• Use English for all name values across plays, tasks, handlers, and blocks.

Rules

Condition placement

• Place when immediately after name when the task has conditions.
• Group related tasks in a block when they share the same when expression.
• Use one when on the block instead of repeating it on individual tasks.

Block structure

• Keep every block-scoped task under an enclosing task name that summarizes the group intent.
• Do not require a second nested name key directly under block: when the enclosing task already provides that summary.
• Add an inner named block only when multiple nested blocks exist and need distinct identities.
• Tag tasks included only for debugging with ["never", "debug"] to exclude them from normal runs.
• Nest a block inside another block when its when condition evaluates a registered variable produced by the outer block's tasks.

Task key order

• Keep task key order: name → when → no_log → become → delegate_to → run_once → environment → module FQCN → args/vars → loop/loop_control → register → changed_when/failed_when → notify.
• Place become and become_user before the module to enable privilege escalation.
• Place delegate_to before the module to target task execution on a different host.
• Place run_once: true before the module for controller-side operations.
• Place environment variables before the module when task-scoped environment variables are needed.
• Omit keys that are not needed for the task; only include keys used in the task in the specified order.

Import vs include policy

• Use ansible.builtin.import_tasks for static task-file composition known at parse time.
• Use ansible.builtin.include_tasks when static import cannot satisfy the use case (including but not limited to: dynamic filenames, loops, or host-fact-driven branching).
• For role composition decisions (import_role vs include_role), see ansible-role.mdc.