Check mode as a merge gate · Ansible

Every gate so far in this part answers yes or no. Lint passes or it does not. The secret scanner finds something or it does not. Those are useful and they are all statements about the text of the change.

This gate is different in kind. Its job is not to decide whether the change is acceptable — it is to produce the artefact that lets a human decide, quickly and conclusively. A --check --diff run against a staging inventory, with its output attached to the pull request, converts review from “can I imagine what this does” into “does this output match the description”.

That is the highest-value thing a pull request in this repository can carry, and it is also the gate most likely to be believed beyond what it proves.

What the gate runs

ansible-playbook -i inventories/staging playbooks/site.yml \
  --check --diff --vault-id stage@"$VAULT_STAGE"

--check puts every module that supports it into a mode where it reports what it would do without doing it. --diff makes the file-managing modules print the literal before-and-after of the content they would write.

The severity of that command is worth being precise about, because it is tempting to file it as read-only and it is not. Check mode is a request that modules honour; a module with no check-mode support behaves according to its own contract, and a task carrying check_mode: false executes for real during a --check run. Part XXV’s mechanics lesson has the full picture. Treat the command as CONFIGURATION against whatever inventory you point it at, and point it at staging.

Exit codes, and the gate that gets them wrong

ansible-playbook distinguishes four outcomes, and this table was established by execution on 2.21.3 rather than from documentation — upstream does not publish it:

Run outcome	Exit code
Success	`0`
Task failure only	`2`
Unreachable host only	`4`
Task failure and unreachable host	`4`

Unreachable takes precedence. That last row is the one that catches people: a run containing both real failures and unreachable hosts reports 4, so a CI job written as “if the exit code is 2, the run failed” classifies it as something else entirely.

The correct gate is the simple one: anything other than 0 is a failure. Then distinguish the causes for the human reading the result, rather than for the branching logic.

Both codes are easy to reproduce in check mode. An undefined variable — the commonest way a change passes in one environment and fails in another — surfaces as a task failure:

Configuration changecheck run, variable missing in this environment— Real output from ansible-core 2.21.3. The play references a variable that production defines and staging does not.

$ ansible-playbook -i inventories/staging playbooks/webservers.yml --check --diff

fatal: [web-stg-01.example.com]: FAILED! => {"msg": "Task failed: Finalization of task args for 'ansible.builtin.debug' failed: Error while resolving value for 'msg': 'webserver_worker_processes' is undefined"}

PLAY RECAP *********************************************************************
web-stg-01.example.com  : ok=0  changed=0  unreachable=0  failed=1  skipped=0  rescued=0  ignored=0

Exit status 2. That failure is a genuine finding and it is one the gate exists to produce: the change assumed a variable that only one environment provides. Fix it in the repository, not by adding a default().

And when the staging hosts cannot be reached at all:

Configuration changecheck run against hosts that are down— The exit code and recap were produced on ansible-core 2.21.3; the connection error text varies with the cause, so it is shown generically here. Note that the failure is classified as unreachable rather than as a task failure.

$ ansible-playbook -i inventories/staging playbooks/gate.yml --check --diff

fatal: [web-stg-01.example.com]: UNREACHABLE! => {"changed": false, "msg": "Failed to connect to the host via ssh", "unreachable": true}

PLAY RECAP *********************************************************************
web-stg-01.example.com  : ok=0  changed=0  unreachable=1  failed=0  skipped=0  rescued=0  ignored=0

Illustrative output

Exit status 4.

The clean run that ran nothing

Here is the failure mode that makes this gate dangerous rather than merely limited, and it is why the gate needs an assertion of its own.

A check run that produces no diff looks the same whether it produced no diff because the change is a no-op, or because no host was in the play. And a pattern that matches no hosts is not an error: Ansible warns, prints hosts (0):, and exits 0. The job is green, the diff is empty, and the pull request appears to have been evaluated.

Three ways to arrive there, all of which have happened:

The play targets a group that exists in production and not in staging.
The staging inventory was emptied or renamed and nobody noticed, because nothing runs against staging except this gate.
A --limit in the CI job refers to a group that was renamed.

The defence is to make the run assert on its own scope. A preflight play that fails when the host count is wrong turns a silently empty gate into a red build:

- name: Gate preflight
  hosts: all
  gather_facts: false
  run_once: true
  tasks:
    - name: Refuse to proceed against an unexpected number of hosts
      ansible.builtin.assert:
        that:
          - ansible_play_hosts_all | length >= expected_min_hosts
        fail_msg: >-
          Expected at least {{ expected_min_hosts }} hosts, found
          {{ ansible_play_hosts_all | length }}. The gate proved nothing.
        success_msg: "{{ ansible_play_hosts_all | length }} hosts in scope."

Set expected_min_hosts per environment in group_vars, and the number is the same one the README records. Part XXIV covers assertion-based guardrails in general; this is the CI-specific application, and it is the one that converts “the gate was green” into “the gate ran”.

This part’s break/fix: green CI, broken production

The scenario in the curriculum has two causes and this gate is one of them.

CI was green. Production broke. The lint profile had excluded the rule that would have caught the change — that is lesson 3’s material — and the --check gate ran against an inventory that no longer resembled production.

The staging inventory had lost its databases group months earlier during an unrelated cleanup. The play that touched the database tier therefore matched nothing in staging, ran zero tasks, produced an empty diff, and exited 0. Nobody was lying and nobody was careless. The gate reported exactly what it observed, which was nothing.

Two cheap defences, and you want both: the host-count assertion above, and a structural-equivalence check that fails when a group present in production is absent from staging. The second is a dozen lines comparing two ansible-inventory --graph outputs, and it is the one that catches the problem before it can produce a misleading green.

Under the hood

The limits the reviewer inherits are real and Part XXV establishes them by execution. Restating the ones that matter for a gate, as opposed to for an operator running a dry run by hand:

Modules differ in check-mode support. Some fully support it, some report changed without being able to compute a real diff, and some are skipped entirely. ansible.builtin.wait_for has check-mode support of none and is skipped. ansible.builtin.command is skipped by default. That means a play whose real work is in a command produces a check run that looks trivially clean.

A clean diff can describe a change that cannot happen. Check mode renders a template against the current variables and shows the result. It does not verify that the target filesystem is writable, that the validate command would pass, or that the service would accept the configuration. Part XXV demonstrates a check run printing a perfect diff for a change the real run could not make.

Sequential dependencies invert the result. If task 2 configures something that task 5 reads, then in check mode task 2 did not really happen, so task 5 evaluates against the old state. Long plays produce check output that diverges further from reality the further down you read.

The practical consequence for the pull request template: state these limits once, next to the attached diff, so that “the check gate is green” never gets read as “this change is safe”. The gate proves that the automation assembles, resolves its variables in this environment, and produces the file contents shown. It does not prove the real run will succeed, and a reviewer who knows the difference will ask for a canary on the changes where it matters.

What happens if the change cannot be dry-run meaningfully?

Some can not. A play whose central task is a command that check mode skips. A change to a role that only runs on first provisioning. A migration that is not idempotent by nature.

Say so, rather than attaching an empty diff and letting it read as a pass.

The honest alternatives, in order of preference:

Make the play dry-runnable. Part XXV’s constructive lesson covers this: creates on the command, check_mode: false on read-only probes, a changed_when that reflects reality. Often the play is not dry-runnable because nobody tried, and the fix improves the play for every other purpose too.
Run it for real against a disposable environment. A Molecule scenario or a throwaway container proves far more than a dry run and is the next lesson’s subject. For a role, this is strictly better evidence.
Canary in production, deliberately. One host, --limit, with someone watching and a stated rollback. This is a legitimate answer when the first two are impossible; what makes it legitimate is that it was chosen rather than defaulted into.
Say the evidence does not exist. A pull request that states “check mode proves nothing here because the work is in a command task; I ran it against one staging host manually, output attached” is far more useful than a green gate that examined nothing.

The failure to avoid is the empty diff presented as a clean one. A gate that cannot see the change should say so, and if it cannot say so, the author should.

What the gate runs

Exit codes, and the gate that gets them wrong

The clean run that ran nothing

Knowledge check