no-changed-when¶

This rule checks that tasks return changes to results or conditions. Unless tasks only read information, you should ensure that they return changes in the following ways:

Register results or conditions and use the changed_when clause.
Use the creates or removes argument.

You should always use the changed_when clause on tasks that do not naturally detect if a change has occurred or not. Some of the most common examples are shell and command modules, which run arbitrary commands.

One very common workaround is to use a boolean value like changed_when: false if the task never changes anything or changed_when: true if it always changes something, but you can also use any expressions, including ones that use the registered result of a task, like in our example below.

This rule also applies to handlers, not only to tasks because they are also tasks.

Problematic Code¶

---
- name: Example playbook
  hosts: localhost
  tasks:
    - name: Does not handle any output or return codes
      ansible.builtin.command: cat {{ my_file | quote }} # <- Does not handle the command output.

Correct Code¶

---
- name: Example playbook
  hosts: localhost
  tasks:
    - name: Handle shell output with return code
      ansible.builtin.command: cat {{ my_file | quote }}
      register: my_output # <- Registers the command output.
      changed_when: my_output.rc != 0 # <- Uses the return code to define when the task has changed.