always, never, tagged and untagged · Ansible

Four tag names are reserved, and their behaviour is easier to state by running it than by describing it. This playbook has one task carrying each of the interesting cases:

- name: always and never
  hosts: local
  gather_facts: false
  tasks:
    - name: always task
      ansible.builtin.debug: {msg: always}
      tags: [always]

    - name: never task
      ansible.builtin.debug: {msg: never}
      tags: [never, destroy]

    - name: plain task
      ansible.builtin.debug: {msg: plain}
      tags: [routine]

    - name: untagged task
      ansible.builtin.debug: {msg: untagged}

Five selections, executed against ansible-core 2.21.3:

Read-only / Safethe complete behaviour table, executed— Each line shows which tasks ran for one selection. Only TASK header lines are shown; the tasks are debug and change nothing.

$ for t in '--tags routine' '--tags destroy' '--tags all' '--tags untagged' '--skip-tags always'; do echo "== $t"; ansible-playbook -i inventory.ini specialtags.yml $t | grep '^TASK'; done

== --tags routine
TASK [always task]
TASK [plain task]

== --tags destroy
TASK [always task]
TASK [never task]

== --tags all
TASK [always task]
TASK [plain task]
TASK [untagged task]

== --tags untagged
TASK [always task]
TASK [untagged task]

== --skip-tags always
TASK [plain task]
TASK [untagged task]

Everything about the four reserved tags is in those five blocks.

`always`

Runs under every selection — including one that names a completely different tag, and including --tags selections that match nothing else at all.

The one thing that suppresses it is naming it explicitly: --skip-tags always. That is the escape hatch, and the last block above is it working.

Where it belongs: preconditions and assertions. A task that verifies the host is what you think it is should run whatever subset the operator selected, because a partial run against the wrong host is not safer than a full one.

- name: refuse to run against a host outside the intended environment
  ansible.builtin.assert:
    that: ansible_facts['hostname'] in groups['web']
    fail_msg: >-
      This play configures the web tier. {{ inventory_hostname }} is not in
      the web group; check --limit before retrying.
  tags: [always]

Part XXII lesson 4 showed the generated role-argument validation task carrying exactly this tag, for exactly this reason.

Where it does not belong: anything that changes state. A task tagged always that installs a package makes every tag selection wider than the operator asked for, and --tags certificates stops being a statement about blast radius.

Blast radius: always tasks are part of every selection you offer

Before publishing a tag scheme, list what runs unconditionally:

grep -rn -B6 'always' playbooks/ roles/*/tasks/ | grep -E 'name:|always'

Every always task is in the blast radius of every --tags invocation anybody will ever type. Read that list and ask whether each entry is something you are happy to run during a narrow emergency change. Assertions: yes. Package installs: no.

`never`

The inverse. A task tagged never is skipped unless something explicitly requests one of its tags — including never itself.

Look at the second and third blocks. --tags destroy runs the never task, because destroy was named. --tags all does not, because all is not a name — it is the wildcard, and the wildcard deliberately does not reach tasks marked never.

The production use is a destructive operation that lives in the playbook, next to the code it belongs with, and cannot execute by accident:

- name: drop and recreate the reporting schema
  community.postgresql.postgresql_db:
    name: reporting
    state: absent
  tags: [never, reset_reporting_schema]

An operator who needs it types --tags reset_reporting_schema. Nobody gets there by running site.yml, by running --tags all, or by a --tags database that happens to overlap. The tag name is the request, and the request has to be exact.

never is a guard against accident, not against intent

--tags all,never runs every never-tagged task in the playbook. That form exists and somebody will eventually find it.

Treat never as protection against the wrong command, not as an authorisation control. If a task must not run without a second person agreeing, the guard is a required variable that has no default:

- name: drop and recreate the reporting schema
  community.postgresql.postgresql_db:
    name: reporting
    state: absent
  when: confirm_destroy_reporting | default('') == 'yes-destroy-reporting'
  tags: [never, reset_reporting_schema]

Now the operator needs the tag and an -e whose value spells out what they are agreeing to. Both appear in shell history, which is the audit trail the tag alone does not give you.

There is a second reason to add the variable, and it is stronger than the audit argument: never can be defeated by tag inheritance. If the role containing this task is imported with tags: [maintenance], the task inherits maintenance, and --tags maintenance then names one of its own tags — which is exactly the condition that opens the guard. Lesson 3 has the executed proof. A when reading a variable is unaffected by any of that.

`tagged` and `untagged`

Two selectors rather than tags you apply. They are how you answer “what did I forget to tag”:

--tags untagged — every task carrying no tags at all, plus always
--tags tagged — every task carrying at least one tag
--skip-tags untagged — everything that has been tagged

The fourth block above is --tags untagged selecting the untagged task and the always task, and nothing else.

Read-only / Safefind the tasks a tag scheme cannot reach— Lists tasks with no tags. Parse-time only; contacts nothing.

ansible-playbook -i inventory/production.ini site.yml --list-tasks --tags untagged

That command is the audit for a partially tagged playbook. Anything it lists is work no --tags invocation can select, which means it can only ever be run as part of the whole play — usually the opposite of what somebody intended when they started adding tags.

--tags all is the fifth selector and it is the default: with no --tags at all, Ansible behaves as --tags all, which is everything except never.

The complete table

Selection	`always`	`never` + `destroy`	tagged `routine`	untagged
(none) / `--tags all`	runs	skipped	runs	runs
`--tags routine`	runs	skipped	runs	skipped
`--tags destroy`	runs	runs	skipped	skipped
`--tags untagged`	runs	skipped	skipped	runs
`--skip-tags always`	skipped	skipped	runs	runs

Under the hood

The reserved names are handled inside the same per-task set comparison that lesson 1 described, as two short-circuits placed around it.

always is checked after the skip list and before the selection list: if the task carries always and always is not in --skip-tags, it is selected without consulting --tags at all. That ordering is why --skip-tags always is the only thing that suppresses it, and why an always task runs even under a --tags selection that matches nothing else in the playbook.

never is checked against the literal contents of the --tags list rather than against the expanded selection. all expands to “every tag present in the playbook” during ordinary matching, but the never check asks whether one of this task’s own tag names — or the string never — was typed. all is neither, so it does not reach the task. --tags all,never names it directly and does.

tagged and untagged are evaluated as predicates on the task’s tag set rather than as membership tests, which is why they can appear in --tags and --skip-tags but never in a playbook. Applying tags: [untagged] to a task gives it a tag, making it tagged, which is the sort of contradiction that is easier to state than to debug.

What happens if you tag a whole role never?

Every task in it inherits never, so the role becomes unreachable except by naming one of its tags — which, if never is the only tag you applied, means --tags never.

That is almost never what you want, because --tags never reaches every never-tagged task in the entire playbook, not just this role’s. The operator who wanted your one dangerous role gets all of them.

Always pair never with a specific name:

- name: decommission the node
  ansible.builtin.import_role:
    name: decommission
  tags: [never, decommission]

Now --tags decommission selects this role and only this role, and site.yml does not touch it. That pairing — never plus one specific name — is the only form of never worth writing.

One caveat that lesson 3 proves by execution: this works because the tags are on the import of a role whose tasks carry no other inherited tag. If you instead have a never task inside a role that is imported under some other tag, that task inherits the other tag and becomes reachable by it. Keep destructive work in its own role, tagged at the import, rather than buried in a role that is tagged for something else.

always

never

tagged and untagged

The complete table

Knowledge check

`always`

`never`

`tagged` and `untagged`