Ansible git Module: Clone Repos & Checkout Commits (ansible.builtin.git Guide)
By Luca Berton · Published 2024-01-01 · Category: installation
Complete guide to ansible.builtin.git module. Clone repositories, checkout specific commits, branches, and tags with practical playbook examples.
How to Checkout a Specific Commit Using Ansible?
Managing code versions effectively is crucial in automation workflows. With Ansible’s ansible.builtin.git module, you can checkout a specific commit from a Git repository, ensuring your infrastructure or deployments use the exact version you need.
I'm Luca Berton, and in this tutorial, I’ll guide you through checking out a specific commit of a Git repository using Ansible.
ansible.builtin.git • Part of ansible-core • Manages Git checkouts • Supports branches, tags, and commit hashes
The ansible.builtin.git module enables automated repository management in Ansible playbooks. You can use it to clone repositories, checkout branches, pull changes, and, importantly, checkout a specific commit by using its SHA-1 hash.
Links • Ansible Git Module Documentation
Playbook I’ll show you how to checkout a specific commit from a Git repository using an Ansible playbook.
Execution
Playbook Code
Explanation: • repo: Defines the Git repository URL. • dest: Specifies where to clone the repository. • version: Points to the exact commit hash to checkout.
Additional Options
Force Checkout a Specific Commit If the repository is already cloned, but you want to force-checkout a commit:
Checkout a Commit Not Part of a Branch If the commit isn't part of any branch or tag, you might need to specify refspec:
Before Execution
After Execution
Handling Detached HEAD State
Since checking out a commit directly places Git in a detached HEAD state, you may want to switch back to a branch after checking out:
Checkout by Commit Hash
Checkout by Tag
Checkout by Branch
Version-Pinned Deployment
Rollback Pattern
Get Latest Tag
FAQ
What does version accept?
Any valid Git ref: branch name, tag, full/short commit SHA, or HEAD.
How do I prevent accidental updates?
Use update: false to skip pulling if repo exists:
What does force: true do?
Discards local changes and resets to the specified version. Without it, the task fails if there are uncommitted local changes.
Checkout Specific Commit
Checkout Branch
Checkout Tag
Deployment with Rollback
Pin Version in Variables
Shallow Clone with Specific Version
Get Deployed Version
FAQ
What happens if the commit doesn't exist?
The task fails with a git error. Always verify the commit/tag exists before deploying.
force: true — will it lose local changes?
Yes — force: true runs git checkout --force and git clean -fd, discarding all local modifications.
How do I deploy from a private repo?
Use SSH with a deploy key:
Clone Repository
Checkout Specific Commit
Checkout Tag
Checkout Branch
SSH Authentication
Deploy Pattern
Shallow Clone
Force Update (Discard Local Changes)
Check If Updated
FAQ
How to use HTTPS with credentials?
force: true vs update: true?
force: true discards local changes. update: true (default) pulls changes but fails if local modifications conflict.
How to clone to a specific user's home?
Use become_user to clone as that user, ensuring proper file ownership.
Conclusion
Now you know how to checkout a specific commit of a Git repository using Ansible. This ensures your automation pipelines deploy and test against exact versions.
Related Articles • ansible.builtin.git Module: Clone & Checkout Git Repositories (Guide) • Ansible builtin command Module: Complete Guide with Examples and Best Practices • Ansible git Module: Clone & Pull Git Repositories (ansible.builtin.git Guide)
Category: installation