ansible-playbook Command Reference

Run an Ansible playbook against an inventory.

ansible-playbook executes the plays in a YAML playbook against the hosts in an inventory. In CI you run it non-interactively with a vault password file and SSH key from secrets.

What it does

ansible-playbook reads a playbook, connects to the targeted inventory hosts, and applies each task in order, reporting changed/ok/failed counts. It is the primary command for configuration management and orchestrated deploys with Ansible.

Common flags and usage

-i INVENTORY: inventory file or dynamic inventory script
--check: dry run, report changes without applying (PR gate)
--diff: show file content changes
--limit HOSTS: restrict to a subset of hosts
--vault-password-file FILE: decrypt vaulted vars non-interactively
-e KEY=VALUE / --extra-vars: pass variables on the command line

Example

shell

- name: Run playbook
  env:
    ANSIBLE_HOST_KEY_CHECKING: 'False'
  run: |
    printf '%s' "${{ secrets.VAULT_PASSWORD }}" > .vault-pass
    ansible-playbook -i inventory/prod site.yml \
      --vault-password-file .vault-pass --diff
    rm -f .vault-pass

In CI

Disable interactive host-key prompts (ANSIBLE_HOST_KEY_CHECKING=False with known SSH targets) and supply the vault password via --vault-password-file from secrets, deleting the file afterward. Run --check --diff on pull requests as a dry-run gate, then apply for real on the deploy branch.

Key takeaways

ansible-playbook applies a playbook to inventory hosts task by task.
Use --vault-password-file from secrets so vaulted vars decrypt unattended.
Run --check --diff on PRs as a dry-run gate before the real apply.