ansible-pull

Pull a playbook from a VCS and execute a default local.yml playbook

$ ansible-pull [[-U|--url]] [repository_url]

$ ansible-pull [[-U|--url]] [repository_url] [playbook]

$ ansible-pull [[-U|--url]] [repository_url] [[-C|--checkout]] [branch] [playbook]

$ ansible-pull [[-U|--url]] [repository_url] [[-i|--inventory-file]] [hosts_file] [playbook]

ansible-pull [options] [playbook.yml]

-U URL, --url=URL
    URL to the playbook repository (required, e.g., git repo).

-C PATH, --checkout=PATH
    Checkout path in repo (default: top-level).

-d DIRECTORY, --directory=DIRECTORY
    Directory to check out repository into (default: ~/ansible-pull).

--clean
    Clean checkout after playbook execution.

--purge
    Purge checkout directory after execution.

-i INVENTORY, --inventory=INVENTORY
    Inventory file or comma-separated hosts.

-u USER, --user=USER
    User to run playbooks as (default: current user).

-k, --ask-vault-pass
    Prompt for vault password.

-v, -vv, -vvv
    Verbose output levels.

--version
    Show version and exit.

ansible-pull inverts the typical Ansible workflow by having target hosts pull configuration playbooks from a version control system (VCS) repository, such as Git, and execute them locally. This is useful for bootstrapping new systems, air-gapped environments, or scenarios where a central control node isn't feasible.

Instead of a control machine pushing changes, each host runs ansible-pull via cron or systemd timer to fetch the latest playbook and apply it idempotently. It supports checkouts to a local directory, inventory files, and various execution options. Playbooks must be self-contained or reference local roles/collections.

Key benefits include scalability for large fleets and reduced network traffic from central orchestration. However, it demands secure repo access (SSH keys or HTTPS) and careful playbook design to avoid infinite loops or security risks from untrusted code.

Requires Git; fetches and runs untrusted code—use signed commits or HTTPS with auth. Not for production without safeguards; may conflict with push-based Ansible. Limited to local execution, no delegation.

ansible-pull -U https://github.com/example/playbooks.git -i localhost, --clean
Runs default playbook from repo on localhost.

Commonly scheduled: 0 * * * * /usr/bin/ansible-pull -U https://git.example.com/ansible.git for hourly pulls.

Introduced in Ansible 1.4 (2014) as pull-mode alternative. Evolved with Ansible 2.x for collections/roles support; maintained in modern Ansible Core by Red Hat community.

ansible-playbook(1), ansible(1), git-pull(1)