Skip to content

ansible-pull

Turns the direction around: the server fetches a playbook from a Git repository and applies it to itself.

ansible-pull output

Syntax

ansible-pull -U REPO_URL [OPTIONS] [PLAYBOOK.yml]

Options

Option Description
-U URL Git repository with the playbooks
PLAYBOOK.yml Playbook to run; without it, <hostname>.yml or local.yml
-C BRANCH Branch or tag to check out
-d DIRECTORY Where to check out the repository (default ~/.ansible/pull/<hostname>)
-o, --only-if-changed Only run if the repository has new commits
-s SECONDS Wait a random time up to this many seconds first, so not all servers start at once
--vault-password-file FILE Password for encrypted files

Examples

Fetch and apply the configuration:

ansible-pull -U https://git.example.com/ops/config.git local.yml
Starting Ansible Pull at 2026-10-26 10:42:17
/usr/bin/ansible-pull -U https://git.example.com/ops/config.git local.yml
localhost | CHANGED => {
    "after": "5c9bef1c4897f55aaf5a87f316a508f096778417",
    "before": null,
    "changed": true
}

PLAY [Base configuration] ******************************************************

TASK [Gathering Facts] *********************************************************
ok: [localhost]

TASK [Message of the day] ******************************************************
changed: [localhost]

PLAY RECAP *********************************************************************
localhost                  : ok=2    changed=1   unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

The first block is the git checkout, then the playbook runs as usual. Depending on the playbook, Ansible also prints warnings about the host pattern; they are harmless.

Only run when something changed:

ansible-pull -U https://git.example.com/ops/config.git -o local.yml
Starting Ansible Pull at 2026-10-26 11:12:17
/usr/bin/ansible-pull -U https://git.example.com/ops/config.git -o local.yml
localhost | SUCCESS => {
    "after": "5c9bef1c4897f55aaf5a87f316a508f096778417",
    "before": "5c9bef1c4897f55aaf5a87f316a508f096778417",
    "changed": false,
    "remote_url_changed": false
}
Repository has not changed, quitting: ...

The playbook in the repository:

cat ~/.ansible/pull/tuxdex-srv/local.yml
- name: Base configuration
  hosts: localhost
  connection: local
  tasks:
    - name: Message of the day
      ansible.builtin.copy:
        content: "Managed by Ansible. Changes will be overwritten.\n"
        dest: ~/motd.txt
        mode: "0644"

When do I need it?

  • For many servers that should configure themselves, for example from a cron job
  • For servers that the control node can't reach, such as machines behind NAT
  • To set up a new server at the end of its installation with a single command

As a cron job or timer

*/30 * * * * ansible-pull -U https://git.example.com/ops/config.git -o -s 300 checks every 30 minutes, only applies changes, and spreads the load. See crontab.

The repository has power over the server

Whoever can push to the repository can run any command on every server that pulls from it. Protect the repository like root access.

ansible-playbook · ansible-vault · git clone · crontab