5 November 2026 · 5 MIN READ
Running Ansible playbooks safely: --syntax-check, --check and --diff
Three review passes that catch most playbook mistakes before they reach a production server — and the honest limits of each.
Why review a playbook at all
A playbook is code that executes on servers you care about, often with elevated privileges. Typing it straight into production works fine until the one time it does not.
Three passes — syntax, dry run, diff — take under a minute together and catch the majority of the mistakes I have actually made: a misnamed variable, a task that would restart the wrong service, a file that would be replaced wholesale.
Pass one: --syntax-check
The syntax check parses the playbook without touching any host. It catches YAML mistakes, bad indentation, and undefined task names. It is fast enough to run every single time, including from CI on every pull request.
What it does not do: validate module arguments, host names, or logic. Passing syntax is the floor, not the ceiling.
Pass two: --check
Check mode runs the playbook against the real inventory but reports what it would change instead of changing it. This is where you learn that a task you thought was idempotent would actually modify three hosts.
Know its limits: command and shell tasks cannot predict their effect, and conditionals that depend on changed state may mislead in check mode. Treat unexpected “changed” lines as questions to answer, not noise.
Pass three: --diff
With --diff, check mode shows you exactly which lines would change in files and templates. Reviewing a diff is reviewing the change itself, in the same format a colleague would expect in a pull request.
# Validate the playbook syntax
ansible-playbook -i inventory.ini site.yml --syntax-check
# Preview supported task changes before applying
ansible-playbook -i inventory.ini site.yml --check --diffWhat the checks cannot catch
The passes above will not save you from:
- Logic that is syntactically valid and operationally wrong (a restart of a service that should not restart).
- side effects inside command/shell tasks.
- Changes to systems outside Ansible’s view — the database the playbook silently assumes exists.
Pair checks with backups and a runbook
Checks reduce the chance of a mistake; they do not remove it. Before anything consequential: take a backup or snapshot, know the rollback step, and keep the runbook written for the next person.
The principle behind the whole sequence: make the process understandable before making it automatic. Keep inputs explicit and pair automation with checks and recovery instructions.