Ambiguous documentation on play and role level tags

[richlv]

Summary

https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_tags.html#adding-tags-to-includes is very clear about how the tags will affect it:

tags on an include_* task apply only to the include itself, not to any tasks within the included file or role

https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_tags.html#adding-tags-to-plays says:

If all the tasks in a play should get the same tag, you can add the tag at the level of the play.

https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_tags.html#adding-tags-to-roles says:

When you incorporate a role in your playbook statically with the roles keyword, Ansible adds any tags you define to all the tasks in the role.

In both of these cases it is not explicitly documented whether and how tagging will apply to the definition itself and/or it's downstream tasks.

Ideally, documentation would allow to clearly determine the following.
If a tag is included for a play or a role:
a) Is it run if no tags are specified?
b) Is the tag passed down to all the tasks?

Issue Type

Documentation Report

Component Name

tags

Ansible Version

$ ansible --version

Configuration

# if using a version older than ansible-core 2.12 you should omit the '-t all'
$ ansible-config dump --only-changed -t all

OS / Environment

Not relevant.

Additional Information

Users could unambiguously determine the behaviour just from reading the documentation.

Code of Conduct

• I agree to follow the Ansible Code of Conduct

[ansibot]

Files identified in the description:

• lib/ansible/playbook/block.py

If these files are incorrect, please update the component name section of the description or use the component bot command.

[bcoca]

The issue is not with role or play level tags, those are always inherited by the contained tasks/blocks/roles.

The special case is the include itself (include_tasks/include_roles) as they are both a dynamic task and an inserted block of tasks/role. That is why you have the keywords on the task apply only to the include itself and they have the apply keyword to set 'inheritable' keywords to the resulting objects. This is not needed for imports as they run prior to execution and no keywords apply to the import itself.

Also, includes still inherit keywords (including tags) from the play objects they are contained in and pass those down to the objects they inject into the play.

[ansible-documentation-bot]

Thanks for your Ansible docs contribution! We talk about Ansible documentation on Matrix at #docs:ansible.im if you ever want to join us and chat about the docs! We meet on Matrix every Tuesday. See the Ansible calendar for meeting details. We welcome additions to our weekly agenda items too. You can add the dawgs-meeting tag to a forum topic to bring it up at the next meeting.