feat: add ansible tag docs
All checks were successful
ci/woodpecker/push/build-and-deploy Pipeline was successful
ci/woodpecker/cron/build-and-deploy Pipeline was successful

This commit is contained in:
Simon Cornet 2026-05-20 09:44:22 +02:00
commit 27849c366e

View file

@ -0,0 +1,35 @@
# Ansible Tags: import_tasks vs include_tasks
**import_tasks (static)**
- Processed at parse time — tasks are inlined into the play before execution
- Tags on the import_tasks statement are inherited by all tasks inside the imported file
- No need to repeat tags inside the imported file
**include_tasks (dynamic)**
- Processed at runtime — tasks are loaded when the include is reached
- Tags on the include_tasks statement apply only to the include itself, not to the tasks inside
- Required when using loop (which import_tasks doesn't support)
- Use apply to propagate tags into included tasks:
```yaml
- name: "example"
ansible.builtin.include_tasks:
file: "example.yaml"
apply:
tags: "my-tag" # propagates to tasks inside
tags: "my-tag" # triggers the include itself
```
Both tags: lines are needed — the outer one ensures the include runs when --tags is used, and apply ensures the tasks inside also match the tag filter.
Running with --tags
- Only tasks matching the specified tags execute
- tags: "always" runs regardless of tag filtering
- Running without --tags executes everything
Best practice
Define tags in one place (main.yaml) and don't repeat them in sub-task files. This avoids confusion and keeps tag management centralized