git¶

Collection Note

This module is part of the ansible.builtin collection. To install the collection, use:

ansible-galaxy collection install ansible.builtin

Added in version 0.0.1.

You need further requirements to be able to use this module, see the Requirements section for details.

Synopsis¶

Manage I(git) checkouts of repositories to deploy files or software.

Requirements¶

The following Python packages are needed on the host that executes this module:

git>=1.7.1 (the command line tool)

Parameters¶

Parameter	Defaults / Choices	Comments
accept_hostkey bool	Default: no	Will ensure or not that C(-o StrictHostKeyChecking=no) is present as an ssh option. Be aware that this disables a protection against MITM attacks. Those using OpenSSH >= 7.5 might want to use O(accept_newhostkey) or set O(ssh_opts) to V(StrictHostKeyChecking=accept-new) instead, it does not remove the MITM issue but it does restrict it to the first attempt. Version Added: 1.5
accept_newhostkey bool	Default: no	As of OpenSSH 7.5, C(-o StrictHostKeyChecking=accept-new) can be used which is safer and will only accepts host keys which are not present or are the same. If V(true), ensure that C(-o StrictHostKeyChecking=accept-new) is present as an ssh option. Version Added: 2.12
archive path		Specify archive file path with extension. If specified, creates an archive file of the specified format containing the tree structure for the source tree. Allowed archive formats ["zip", "tar.gz", "tar", "tgz"]. This will clone and perform git archive from local directory as not all git servers support git archive. Version Added: 2.4
archive_prefix str		Specify a prefix to add to each file path in archive. Requires O(archive) to be specified. Version Added: 2.10
bare bool	Default: no	If V(true), repository will be created as a bare repo, otherwise it will be a standard repo with a workspace. Version Added: 1.4
clone bool	Default: yes	If V(false), do not clone the repository even if it does not exist locally. Version Added: 1.9
depth int		Create a shallow clone with a history truncated to the specified number or revisions. The minimum possible value is V(1), otherwise ignored. Needs I(git>=1.9.1) to work correctly. Version Added: 1.2
dest path required		The path of where the repository should be checked out. This is equivalent to C(git clone [repo_url] [directory]). The repository named in O(repo) is not appended to this path and the destination directory must be empty. This parameter is required, unless O(clone) is set to V(false).
executable path		Path to git executable to use. If not supplied, the normal mechanism for resolving binary paths will be used. Version Added: 1.4
force bool	Default: no	If V(true), any modified files in the working repository will be discarded. Prior to 0.7, this was always V(true) and could not be disabled. Prior to 1.9, the default was V(true). Version Added: 0.7
gpg_allowlist list / elements=str		A list of trusted GPG fingerprints to compare to the fingerprint of the GPG-signed commit. Only used when O(verify_commit=yes). Use of this feature requires Git 2.6+ due to its reliance on git's C(--raw) flag to C(verify-commit) and C(verify-tag). Alias O(gpg_allowlist) is added in version 2.17. Alias O(gpg_whitelist) is deprecated and will be removed in version 2.21. Version Added: 2.9
key_file path		Specify an optional private key file path, on the target host, to use for the checkout. This ensures C(IdentitiesOnly=yes) is present in O(ssh_opts). Version Added: 1.5
recursive bool	Default: yes	If V(false), repository will be cloned without the C(--recursive) option, skipping sub-modules. Version Added: 1.6
reference str		Reference repository (see C(git clone --reference ...)). Version Added: 1.4
refspec str		Add an additional refspec to be fetched. If version is set to a I(SHA-1) not reachable from any branch or tag, this option may be necessary to specify the ref containing the I(SHA-1). Uses the same syntax as the C(git fetch) command. An example value could be "refs/meta/config". Version Added: 1.9
remote str	Default: origin	Name of the remote.
repo str required		git, SSH, or HTTP(S) protocol address of the git repository. Avoid embedding usernames and passwords within Git repository URLs. This practice is insecure and can lead to unauthorized access to your repositories. For secure authentication, configure SSH keys (recommended) or use a credential helper. See Git documentation on SSH keys/credential helpers for instructions.
separate_git_dir path		The path to place the cloned repository. If specified, Git repository can be separated from working tree. Version Added: 2.7
single_branch bool	Default: no	Clone only the history leading to the tip of the specified revision. Version Added: 2.11
ssh_opts str		Options git will pass to ssh when used as protocol, it works via C(git)'s E(GIT_SSH)/E(GIT_SSH_COMMAND) environment variables. For older versions it appends E(GIT_SSH_OPTS) (specific to this module) to the variables above or via a wrapper script. Other options can add to this list, like O(key_file) and O(accept_hostkey). An example value could be C(-o StrictHostKeyChecking=no) (although this particular option is better set by O(accept_hostkey)). The module ensures that C(BatchMode=yes) is always present to avoid prompts. Version Added: 1.5
track_submodules bool	Default: no	If V(true), submodules will track the latest commit on their master branch (or other branch specified in C(.gitmodules)). If V(false), submodules will be kept at the revision specified by the main project. This is equivalent to specifying the C(--remote) flag to git submodule update. Version Added: 1.8
umask raw		The umask to set before doing any checkouts, or any other repository maintenance. Version Added: 2.2
update bool	Default: yes	If V(false), do not retrieve new revisions from the origin repository. Operations like archive will work on the existing (old) repository and might not respond to changes to the options version or remote. Version Added: 1.2
verify_commit bool	Default: no	If V(true), when cloning or checking out a O(version) verify the signature of a GPG signed commit. This requires git version>=2.1.0 to be installed. The commit MUST be signed and the public key MUST be present in the GPG keyring. Version Added: 2.0
version str	Default: HEAD	What version of the repository to check out. This can be the literal string V(HEAD), a branch name, a tag name. It can also be a I(SHA-1) hash, in which case O(refspec) needs to be specified if the given revision is not already available.

Notes¶

Note

If the task seems to be hanging, first verify remote host is in C(known_hosts). SSH will prompt user to authorize the first contact with a remote host. To avoid this prompt, one solution is to use the option accept_hostkey. Another solution is to add the remote host public key in C(/etc/ssh/ssh_known_hosts) before calling the git module, with the following command: C(ssh-keyscan -H remote_host.com >> /etc/ssh/ssh_known_hosts).

Examples¶

- name: Git checkout
  ansible.builtin.git:
    repo: 'https://github.com/ansible/ansible.git'
    dest: /tmp/checkout
    version: release-0.22

- name: Read-write git checkout from github
  ansible.builtin.git:
    repo: git@github.com:ansible/ansible.git
    dest: /tmp/checkout

- name: Just ensuring the repo checkout exists
  ansible.builtin.git:
    repo: 'https://github.com/ansible/ansible.git'
    dest: /tmp/checkout
    update: no

- name: Just get information about the repository whether or not it has already been cloned locally
  ansible.builtin.git:
    repo: git@github.com:ansible/ansible.git
    dest: /tmp/checkout
    clone: no
    update: no

- name: Checkout a github repo and use refspec to fetch all pull requests
  ansible.builtin.git:
    repo: 'https://github.com/ansible/ansible.git'
    dest: /tmp/checkout
    refspec: '+refs/pull/*:refs/heads/*'

- name: Create git archive from repo
  ansible.builtin.git:
    repo: git@github.com:ansible/ansible.git
    dest: /tmp/checkout
    archive: /tmp/ansible.zip

- name: Clone a repo with separate git directory
  ansible.builtin.git:
    repo: 'https://github.com/ansible/ansible.git'
    dest: /tmp/checkout
    separate_git_dir: /tmp/repo

- name: Example clone of a single branch
  ansible.builtin.git:
    repo: git@github.com:ansible/ansible.git
    dest: /tmp/checkout
    single_branch: yes
    version: master

- name: Avoid hanging when http(s) password is missing
  ansible.builtin.git:
    repo: 'https://github.com/ansible/ansible.git'
    dest: /tmp/checkout
  environment:
    GIT_TERMINAL_PROMPT: 0 # reports "terminal prompts disabled" on missing password
    # or GIT_ASKPASS: /bin/true # for git before version 2.3.0, reports "Authentication failed" on missing password

Return Values¶

Key	Data Type	Description	Returned
after	str	Last commit revision of the repository retrieved during the update.	success
before	str	Commit revision before the repository was updated, "null" for new repository.	success
git_dir_before	str	Contains the original path of .git directory if it is changed.	success
git_dir_now	str	Contains the new path of .git directory if it is changed.	success
remote_url_changed	bool	Contains True or False whether or not the remote URL was changed.	success

Authors¶

Ansible Core Team
Michael Dehaan