ansible.builtin.git – Deploy software (or files) from git checkouts
Note
This module is part of ansible-core
and included in all Ansible
installations. In most cases, you can use the short
module name
git
even without specifying the collections:
keyword.
However, 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
Requirements
The below requirements are needed on the host that executes this module.
git>=1.7.1 (the command line tool)
Parameters
Parameter |
Comments |
---|---|
If Choices:
|
|
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. |
|
Specify a prefix to add to each file path in archive. Requires archive to be specified. |
|
If Choices:
|
|
If Choices:
|
|
Create a shallow clone with a history truncated to the specified number or revisions. The minimum possible value is |
|
The path of where the repository should be checked out. This is equivalent to |
|
Path to git executable to use. If not supplied, the normal mechanism for resolving binary paths will be used. |
|
If Choices:
|
|
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 Default: [] |
|
Specify an optional private key file path, on the target host, to use for the checkout. |
|
If Choices:
|
|
Reference repository (see “git clone –reference …”). |
|
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 |
|
Name of the remote. Default: “origin” |
|
git, SSH, or HTTP(S) protocol address of the git repository. |
|
The path to place the cloned repository. If specified, Git repository can be separated from working tree. |
|
Clone only the history leading to the tip of the specified revision. Choices:
|
|
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). |
|
If Choices:
|
|
The umask to set before doing any checkouts, or any other repository maintenance. |
|
If Operations like archive will work on the existing (old) repository and might not respond to changes to the options version or remote. Choices:
|
|
If Choices:
|
|
What version of the repository to check out. This can be the literal string Default: “HEAD” |
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:
repo: https://github.com/ansible/ansible-examples.git
dest: /src/ansible-examples
single_branch: yes
version: 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 |
Description |
---|---|
Last commit revision of the repository retrieved during the update. Returned: success Sample: “4c020102a9cd6fe908c9a4a326a38f972f63a903” |
|
Commit revision before the repository was updated, “null” for new repository. Returned: success Sample: “67c04ebe40a003bda0efb34eacfb93b0cafdf628” |
|
Contains the original path of .git directory if it is changed. Returned: success Sample: “/path/to/old/git/dir” |
|
Contains the new path of .git directory if it is changed. Returned: success Sample: “/path/to/new/git/dir” |
|
Contains True or False whether or not the remote URL was changed. Returned: success Sample: true |
|
List of warnings if requested features were not available due to a too old git version. Returned: error Sample: “git version is too old to fully support the depth argument. Falling back to full checkouts.” |
Authors
Ansible Core Team
Michael DeHaan