ansible.builtin.git – Deploy software (or files) from git checkouts
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 |
|
If |
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 |
|
If |
clone boolean added in 1.9 of ansible.builtin |
|
If |
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 | |
dest path / required |
The path of where the repository should be checked out. This is equivalent to | |
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 |
|
If |
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 |
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 |
|
If |
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 | |
remote string |
Default: "origin" |
Name of the remote. |
repo string / required |
git, SSH, or HTTP(S) protocol address of the git repository.
| |
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 |
|
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 by accept_hostkey). | |
track_submodules boolean added in 1.8 of ansible.builtin |
|
If |
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 |
|
If 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 |
|
If |
version string |
Default: "HEAD" |
What version of the repository to check out. This can be the literal string |
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. - Supports
check_mode
.
Examples
- name: Git checkout
ansible.builtin.git:
repo: 'https://foosball.example.org/path/to/repo.git'
dest: /srv/checkout
version: release-0.22
- name: Read-write git checkout from github
ansible.builtin.git:
repo: [email protected]:mylogin/hello.git
dest: /home/mylogin/hello
- name: Just ensuring the repo checkout exists
ansible.builtin.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
ansible.builtin.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
ansible.builtin.git:
repo: https://github.com/ansible/ansible-examples.git
dest: /src/ansible-examples
refspec: '+refs/pull/*:refs/heads/*'
- name: Create git archive from repo
ansible.builtin.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
ansible.builtin.git:
repo: https://github.com/ansible/ansible-examples.git
dest: /src/ansible-examples
separate_git_dir: /src/ansible-examples.git
- name: Example clone of a single branch
ansible.builtin.git:
single_branch: yes
branch: master
- name: Avoid hanging when http(s) password is missing
ansible.builtin.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 is changed.
Sample: /path/to/old/git/dir |
git_dir_now string |
success |
Contains the new path of .git directory if it is 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
© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.11/collections/ansible/builtin/git_module.html