ansible.builtin.git Module: Clone & Checkout Git Repositories (Guide)

By Luca Berton · Published 2024-01-01 · Category: installation

How to clone and checkout Git repositories with Ansible git module (ansible.builtin.git). Deploy code from GitHub, manage branches, tags, force updates.

ansible.builtin.git Module: Clone & Checkout Git Repositories (Guide)

How to checkout git repository via HTTPS?

Ansible checkout git repository

Today we're talking about Ansible module git. The full name is ansible.builtin.git which means is part of the collection of modules "builtin" with ansible and shipped with it. This module is pretty stable and out for years. The purpose is to Deploy software (or files) from git checkouts in our managed hosts. If you would like to fetch via SSH please refer to: Checkout git repository SSH - Ansible module git

Parameters and Return Values

The parameter list is pretty wide but I'll summarize the most useful.

repo _path_
dest _string_
update _boolean_

The only required parameters are "repo" and "dest".

"repo" specifies the source repository URL.

"dest" specify the destination path.

The "update" retrieves new revisions from the already synched origin repository.

after _string_

The most interesting return value is "after" which contains the last commit after the update process.

Demo

Let's jump in a real-life playbook to checkout a git repository with Ansible

---
- name: git module Playbook
  hosts: all
  become: true
  tasks:
    - name: ensure git pkg installed
      ansible.builtin.yum:
        name: git
        state: present

    - name: checkout git repo
      ansible.builtin.git:
        repo: https://github.com/lucab85/ansible-pilot.git
        dest: /home/devops/ansible-pilot

code with ❤️ in GitHub

Conclusion

Now you know how to checkout git repository via HTTPS with Ansible.

Advanced Git Module Usage

Clone a specific branch

- name: Clone develop branch
  ansible.builtin.git:
    repo: https://github.com/ansible/ansible.git
    dest: /opt/ansible
    version: develop

Clone a specific tag

- name: Clone release tag
  ansible.builtin.git:
    repo: https://github.com/ansible/ansible.git
    dest: /opt/ansible
    version: v2.17.0

Clone with SSH key (private repos)

- name: Clone private repo via SSH
  ansible.builtin.git:
    repo: git@github.com:myorg/private-repo.git
    dest: /opt/private-repo
    key_file: /home/deploy/.ssh/deploy_key
    accept_hostkey: true

Shallow clone (faster, saves disk)

- name: Shallow clone (depth 1)
  ansible.builtin.git:
    repo: https://github.com/ansible/ansible.git
    dest: /opt/ansible
    depth: 1

Force update (discard local changes)

- name: Force pull latest
  ansible.builtin.git:
    repo: https://github.com/myorg/myapp.git
    dest: /opt/myapp
    force: true
    version: main

Clone with authentication (HTTPS token)

- name: Clone with GitHub token
  ansible.builtin.git:
    repo: "https://{{ github_token }}@github.com/myorg/private-repo.git"
    dest: /opt/private-repo
  no_log: true  # Hide token from logs

Key Parameters Reference

Parameter	Type	Description
`repo`	string	Repository URL (HTTPS or SSH)
`dest`	string	Local directory to clone into
`version`	string	Branch, tag, or commit hash
`depth`	int	Shallow clone depth
`force`	bool	Discard local modifications
`key_file`	string	SSH private key for authentication
`accept_hostkey`	bool	Auto-accept SSH host keys
`update`	bool	Pull latest if repo already cloned
`recursive`	bool	Initialize submodules
`single_branch`	bool	Clone only the specified branch

Common Deployment Pattern

---
- name: Deploy application from Git
  hosts: webservers
  become: true
  vars:
    app_repo: https://github.com/myorg/myapp.git
    app_dest: /var/www/myapp
    app_branch: main
  tasks:
    - name: Install git
      ansible.builtin.package:
        name: git
        state: present

    - name: Clone/update application
      ansible.builtin.git:
        repo: "{{ app_repo }}"
        dest: "{{ app_dest }}"
        version: "{{ app_branch }}"
        force: true
      register: git_result
      notify: restart app

    - name: Show commit hash
      ansible.builtin.debug:
        msg: "Deployed commit: {{ git_result.after }}"

  handlers:
    - name: restart app
      ansible.builtin.systemd:
        name: myapp
        state: restarted

FAQ

How do I clone from GitLab or Bitbucket?

Same syntax — just change the URL:

# GitLab
repo: https://gitlab.com/myorg/myapp.git

# Bitbucket
repo: https://bitbucket.org/myorg/myapp.git

How do I handle "destination already exists" error?

This means the dest directory exists but isn't a Git repo. Either remove it first or use force: true.

Why does the task always show "changed"?

The git module compares commit hashes. If the remote has new commits, it shows changed. Use update: false to skip pulling.

Category: installation

Watch the video: ansible.builtin.git Module: Clone & Checkout Git Repositories (Guide) — Video Tutorial

Browse all Ansible tutorials · AnsiblePilot Home

AnsiblePilot — Master Ansible Automation

Popular Topics

About Luca Berton