diff --git a/docs/docsite/rst/user_guide/playbooks_tags.rst b/docs/docsite/rst/user_guide/playbooks_tags.rst index 00c86009a39..82fd91ff7a0 100644 --- a/docs/docsite/rst/user_guide/playbooks_tags.rst +++ b/docs/docsite/rst/user_guide/playbooks_tags.rst @@ -129,11 +129,23 @@ Example:: tags: - tag1 -There are another 3 special keywords for tags, ``tagged``, ``untagged`` and ``all``, which run only tagged, only untagged -and all tasks respectively. +.. versionadded:: 2.5 + +Another special tag is ``never``, which will prevent a task from running unless a tag is specifically requested. -By default ansible runs as if ``--tags all`` had been specified. +Example:: + + tasks: + - debug: msg='{{ showmevar}}' + tags: [ 'never', 'debug' ] + +In this example, the task will only run when the ``debug`` or ``never`` tag is explicitly requested. + + +There are another 3 special keywords for tags: ``tagged``, ``untagged`` and ``all``, which run only tagged, only untagged +and all tasks respectively. +By default, Ansible runs as if ``--tags all`` had been specified. .. seealso:: diff --git a/test/integration/targets/tags/runme.sh b/test/integration/targets/tags/runme.sh index d1f26c41d0a..a8b1c90e1ae 100755 --- a/test/integration/targets/tags/runme.sh +++ b/test/integration/targets/tags/runme.sh @@ -35,3 +35,7 @@ export LC_ALL=en_US.UTF-8 # Run a tag from a list of tags and always [ "$("${COMMAND[@]}" --tags café | grep -F Task_with | xargs)" = \ "Task_with_always_tag TAGS: [always] Task_with_list_of_tags TAGS: [café, press]" ] + +# Run tag with never +[ "$("${COMMAND[@]}" --tags donever | grep -F Task_with | xargs)" = \ +"Task_with_always_tag TAGS: [always] Task_with_never_tag TAGS: [donever, never]" ] diff --git a/test/integration/targets/tags/test_tags.yml b/test/integration/targets/tags/test_tags.yml index f7e0467fe70..5f575da7627 100644 --- a/test/integration/targets/tags/test_tags.yml +++ b/test/integration/targets/tags/test_tags.yml @@ -20,3 +20,6 @@ - press - name: Task_without_tag debug: msg= + - name: Task_with_never_tag + debug: msg=NEVER + tags: ['never', 'donever']