Docs4dev
Docs
ansible / 2.4 / git_module.html

git - Deploy software (or files) from git checkouts

Synopsis

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

Requirements (on host that executes module)

  • git>=1.7.1 (the command line tool)

Options

parameter required default choices comments
accept_hostkey
(added in 1.5)
no no
  • yes
  • no
if yes, ensure that "-o StrictHostKeyChecking=no" is present as an ssh options.
archive
(added in 2.4)
no
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"]
bare
(added in 1.4)
no no
  • yes
  • no
if yes, repository will be created as a bare repo, otherwise it will be a standard repo with a workspace.
clone
(added in 1.9)
no yes
  • yes
  • no
If no, do not clone the repository if it does not exist locally
depth
 no
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
 yes
The path of where the repository should be checked out. This parameter is required, unless clone is set to no.
executable
(added in 1.4)
no
Path to git executable to use. If not supplied, the normal mechanism for resolving binary paths will be used.
force
 no no
  • yes
  • no
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`
key_file
(added in 1.5)
no None
Specify an optional private key file to use for the checkout.
recursive
(added in 1.6)
no yes
  • yes
  • no
if no, repository will be cloned without the --recursive option, skipping sub-modules.
reference
(added in 1.4)
no
Reference repository (see "git clone --reference ...")
refspec
(added in 1.9)
no
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
 no origin
Name of the remote.
repo
 yes
git, SSH, or HTTP(S) protocol address of the git repository.
aliases: name
ssh_opts
(added in 1.5)
no None
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
(added in 1.8)
no no
  • yes
  • no
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
(added in 2.2)
no
The umask to set before doing any checkouts, or any other repository maintenance.
update
 no yes
  • yes
  • no
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
(added in 2.0)
no no
  • yes
  • no
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
 no HEAD
What version of the repository to check out. This can be the 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.

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://git@github.com/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

Return Values

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

name description returned type sample
after
last commit revision of the repository retrieved during the update
success string 4c020102a9cd6fe908c9a4a326a38f972f63a903
before
commit revision before the repository was updated, "null" for new repository
success string 67c04ebe40a003bda0efb34eacfb93b0cafdf628
remote_url_changed
Contains True or False whether or not the remote URL was changed.
success boolean True
warnings
List of warnings if requested features were not available due to a too old git version.
error string Your git version is too old to fully support the depth argument. Falling back to full checkouts.

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.

Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

Maintenance Info

For more information about Red Hat’s this support of this module, please refer to this knowledge base article<https://access.redhat.com/articles/rhel-top-support-policies>

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.4/git_module.html