ansible.builtin.git – Deploy software (or files) from git checkouts

Note

This module is part of ansible-base and included in all Ansible installations. In most cases, you can use the short module name git even without specifying the collections: keyword. Despite that, we recommend you use the FQCN for easy linking to the module documentation and to avoid conflicting with other collections that may have the same module name.

New in version 0.0.1: of ansible.builtin

Synopsis

• Manage git checkouts of repositories to deploy files or software.

Requirements

The below requirements are needed on the host that executes this module.

• git>=1.7.1 (the command line tool)

Parameters

Parameter	Choices/Defaults	Comments
accept_hostkey boolean added in 1.5 of ansible.builtin	Choices: no ← yes	if yes, ensure that "-o StrictHostKeyChecking=no" is present as an ssh option.
archive path added in 2.4 of ansible.builtin		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.
archive_prefix string added in 2.10 of ansible.builtin		Specify a prefix to add to each file path in archive. Requires archive to be specified.
bare boolean added in 1.4 of ansible.builtin	Choices: no ← yes	if yes, repository will be created as a bare repo, otherwise it will be a standard repo with a workspace.
clone boolean added in 1.9 of ansible.builtin	Choices: no yes ←	If no, do not clone the repository even if it does not exist locally
depth integer added in 1.2 of ansible.builtin		Create a shallow clone with a history truncated to the specified number or revisions. The minimum possible value is 1, otherwise ignored. Needs git>=1.9.1 to work correctly.
dest path / required		The path of where the repository should be checked out. This is equivalent to git clone [repo_url] [directory]. The repository named in repo is not appended to this path and the destination directory must be empty. This parameter is required, unless clone is set to no.
executable path added in 1.4 of ansible.builtin		Path to git executable to use. If not supplied, the normal mechanism for resolving binary paths will be used.
force boolean added in 0.7 of ansible.builtin	Choices: no ← yes	If yes, any modified files in the working repository will be discarded. Prior to 0.7, this was always 'yes' and could not be disabled. Prior to 1.9, the default was `yes`
gpg_whitelist list / elements=string added in 2.9 of ansible.builtin	Default: []	A list of trusted GPG fingerprints to compare to the fingerprint of the GPG-signed commit. Only used when verify_commit=yes. Use of this feature requires Git 2.6+ due to its reliance on git's --raw flag to verify-commit and verify-tag.
key_file path added in 1.5 of ansible.builtin		Specify an optional private key file path, on the target host, to use for the checkout.
recursive boolean added in 1.6 of ansible.builtin	Choices: no yes ←	if no, repository will be cloned without the --recursive option, skipping sub-modules.
reference string added in 1.4 of ansible.builtin		Reference repository (see "git clone --reference ...")
refspec string added in 1.9 of ansible.builtin		Add an additional refspec to be fetched. If version is set to a SHA-1 not reachable from any branch or tag, this option may be necessary to specify the ref containing the SHA-1. Uses the same syntax as the git fetch command. An example value could be "refs/meta/config".
remote string	Default: "origin"	Name of the remote.
repo string / required		git, SSH, or HTTP(S) protocol address of the git repository. aliases: name
separate_git_dir path added in 2.7 of ansible.builtin		The path to place the cloned repository. If specified, Git repository can be separated from working tree.
single_branch boolean added in 2.11 of ansible.builtin	Choices: no ← yes	Clone only the history leading to the tip of the specified branch
ssh_opts string added in 1.5 of ansible.builtin		Creates a wrapper script and exports the path as GIT_SSH which git then automatically uses to override ssh arguments. An example value could be "-o StrictHostKeyChecking=no" (although this particular option is better set via accept_hostkey).
track_submodules boolean added in 1.8 of ansible.builtin	Choices: no ← yes	if yes, submodules will track the latest commit on their master branch (or other branch specified in .gitmodules). If no, submodules will be kept at the revision specified by the main project. This is equivalent to specifying the --remote flag to git submodule update.
umask raw added in 2.2 of ansible.builtin		The umask to set before doing any checkouts, or any other repository maintenance.
update boolean added in 1.2 of ansible.builtin	Choices: no yes ←	If no, 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.
verify_commit boolean added in 2.0 of ansible.builtin	Choices: no ← yes	if yes, when cloning or checking out a 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 string	Default: "HEAD"	What version of the repository to check out. This can be the literal string HEAD, a branch name, a tag name. It can also be a SHA-1 hash, in which case 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 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 /etc/ssh/ssh_known_hosts before calling the git module, with the following command: ssh-keyscan -H remote_host.com >> /etc/ssh/ssh_known_hosts.

Examples

- name: Git checkout
  git:
    repo: 'https://foosball.example.org/path/to/repo.git'
    dest: /srv/checkout
    version: release-0.22

- name: Read-write git checkout from github
  git:
    repo: git@github.com:mylogin/hello.git
    dest: /home/mylogin/hello

- name: Just ensuring the repo checkout exists
  git:
    repo: 'https://foosball.example.org/path/to/repo.git'
    dest: /srv/checkout
    update: no

- name: Just get information about the repository whether or not it has already been cloned locally
  git:
    repo: 'https://foosball.example.org/path/to/repo.git'
    dest: /srv/checkout
    clone: no
    update: no

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

- name: Create git archive from repo
  git:
    repo: https://github.com/ansible/ansible-examples.git
    dest: /src/ansible-examples
    archive: /tmp/ansible-examples.zip

- name: Clone a repo with separate git directory
  git:
    repo: https://github.com/ansible/ansible-examples.git
    dest: /src/ansible-examples
    separate_git_dir: /src/ansible-examples.git

# Example clone of a single branch
- git:
    single_branch: yes
    branch: master

- name: avoid hanging when http(s) password is missing
  git:
    repo: https://github.com/ansible/could-be-a-private-repo
    dest: /src/from-private-repo
  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

Common return values are documented here, the following are the fields unique to this module:

Key	Returned	Description
after string	success	last commit revision of the repository retrieved during the update Sample: 4c020102a9cd6fe908c9a4a326a38f972f63a903
before string	success	commit revision before the repository was updated, "null" for new repository Sample: 67c04ebe40a003bda0efb34eacfb93b0cafdf628
git_dir_before string	success	Contains the original path of .git directory if it's changed Sample: /path/to/old/git/dir
git_dir_now string	success	Contains the new path of .git directory if it's changed Sample: /path/to/new/git/dir
remote_url_changed boolean	success	Contains True or False whether or not the remote URL was changed. Sample: True
warnings string	error	List of warnings if requested features were not available due to a too old git version. Sample: git version is too old to fully support the depth argument. Falling back to full checkouts.

Authors

• Ansible Core Team
• Michael DeHaan