Run an Ansible Playbook from a Git Repository

Keep playbooks in Git and let Kestra run them. This blueprint clones your infrastructure repository into a Kestra WorkingDirectory, then executes the committed Ansible playbook against a machine list resolved at runtime. Nothing is copy-pasted into the flow: the repo remains the single source of truth for inventory and playbooks, while Kestra supplies scheduling, credentials, containerized execution, and logs.

How it works

1. The getDeployMachinesListFromAPI task (io.kestra.plugin.core.output.OutputValues) stands in for a real CMDB or IPAM lookup and exposes a structured machines list (hostname, IP, owner) that downstream tasks or subflows can iterate over.
2. The runAnsible task (io.kestra.plugin.core.flow.WorkingDirectory) creates a shared filesystem for its children, so the clone and the playbook run see the same files.
3. Inside it, cloneSourceCode (io.kestra.plugin.git.Clone) pulls the main branch of your automation repository, authenticating with GITHUB_USERNAME and GITHUB_ACCESS_TOKEN secrets.
4. ansiblePlaybook (io.kestra.plugin.ansible.cli.AnsibleCLI) runs ansible-playbook -i ansible/inventory.ini ansible/playbook.yml inside the cytopia/ansible:latest-tools container, so workers need no local Ansible installation.

What you get

• GitOps-style configuration management: the playbook that runs is the playbook that was reviewed and merged.
• Containerized Ansible execution with zero worker-side dependencies.
• A structured machine inventory output ready for ForEach fan-out or subflow dispatch.
• Central logging of every playbook run, with the exact commit implied by the branch clone.

Who it's for

• Infrastructure teams already keeping Ansible content in Git who need a scheduler and audit trail.
• Platform engineers replacing Ansible Tower/AWX jobs with declarative workflows.
• Ops teams that want playbook runs triggerable by events, schedules, or upstream flows.

Why orchestrate this with Kestra

Running ansible-playbook from a laptop leaves no trace and depends on whoever has the repo checked out. Kestra clones a fresh copy every run, executes in a pinned container image, injects Git credentials from its secret store, and records logs and timings per execution. The WorkingDirectory pattern generalizes: add linting, inventory generation, or post-run verification tasks that all share the same checkout.

Prerequisites

• A Git repository containing ansible/inventory.ini and ansible/playbook.yml (adjust paths to your layout).
• Network access from the Kestra worker to the managed hosts.
• Docker available to the worker for the Ansible container image.

Secrets

• GITHUB_USERNAME: user or bot account allowed to clone the repository.
• GITHUB_ACCESS_TOKEN: personal access token used as the clone password.

Quick start

1. Add the secrets above to your Kestra namespace (drop them for public repositories).
2. Point cloneSourceCode at your repository and fix the playbook and inventory paths.
3. Execute the flow and follow the playbook output in the Kestra logs.
4. Add a io.kestra.plugin.core.trigger.Schedule trigger for recurring configuration runs.

How to extend

• Replace the stub machine list with io.kestra.plugin.core.http.Request against your CMDB, and render a dynamic inventory from it.
• Fan out per machine with io.kestra.plugin.core.flow.ForEach and pass --limit to Ansible.
• Add ansible-lint as a gate task before the playbook run.
• Pass Kestra inputs to the playbook with -e extra vars, for example the selected image_names.

Links

• Ansible plugin docs: https://kestra.io/plugins/plugin-ansible
• Git Clone task docs: https://kestra.io/plugins/plugin-git/io.kestra.plugin.git.clone
• Ansible orchestration with Kestra: https://kestra.io/orchestration/ansible