git – Deploy software (or files) from git checkouts
git – Deploy software (or files) from git checkouts
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 |
|
if |
archive - added in 2.4 |
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. | |
bare boolean added in 1.4 |
|
if |
clone boolean added in 1.9 |
|
If |
depth - |
Create a shallow clone with a history truncated to the specified number or revisions. The minimum possible value is | |
dest - / required |
The path of where the repository should be checked out. This parameter is required, unless | |
executable - added in 1.4 |
Path to git executable to use. If not supplied, the normal mechanism for resolving binary paths will be used. | |
force boolean |
|
If |
key_file - added in 1.5 |
Specify an optional private key file path, on the target host, to use for the checkout. | |
recursive boolean added in 1.6 |
|
if |
reference - added in 1.4 |
Reference repository (see "git clone --reference ...") | |
refspec - added in 1.9 |
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 - |
Default: "origin" |
Name of the remote. |
repo - / required |
git, SSH, or HTTP(S) protocol address of the git repository.
| |
separate_git_dir - added in 2.7 |
The path to place the cloned repository. If specified, Git repository can be separated from working tree. | |
ssh_opts - added in 1.5 |
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" | |
track_submodules boolean added in 1.8 |
|
if |
umask - added in 2.2 |
The umask to set before doing any checkouts, or any other repository maintenance. | |
update boolean |
|
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 |
|
if |
version - |
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.
Examples
# Example git checkout from Ansible Playbooks
- git:
repo: 'https://foosball.example.org/path/to/repo.git'
dest: /srv/checkout
version: release-0.22
# Example read-write git checkout from github
- git:
repo: ssh://[email protected]/mylogin/hello.git
dest: /home/mylogin/hello
# Example just ensuring the repo checkout exists
- git:
repo: 'https://foosball.example.org/path/to/repo.git'
dest: /srv/checkout
update: no
# Example 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
# Example 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/*'
# Example Create git archive from repo
- git:
repo: https://github.com/ansible/ansible-examples.git
dest: /src/ansible-examples
archive: /tmp/ansible-examples.zip
# Example 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
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: Your git version is too old to fully support the depth argument. Falling back to full checkouts. |
Status
- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Core Team. [core]
Red Hat Support
More information about Red Hat’s support of this module is available from this Red Hat Knowledge Base article.
Authors
- Ansible Core Team
- Michael DeHaan
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.7/modules/git_module.html