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

How to checkout git repository via HTTPS?

I'm going to show you a live Playbook with some simple Ansible code. I'm Luca Berton and welcome to today's episode of Ansible Pilot

See also: Ansible git Clone via SSH: Deploy Keys & Repository Guide

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.

See also: Ansible git Module: Clone Repos & Checkout Commits (ansible.builtin.git Guide)

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.

See also: Ansible win_ping Module: Test Windows Host Connectivity (Examples)

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.

Related Articles

• using become for sudo in Ansible • Ansible role best practices