States to manage git repositories and git configuration
Important
Before using git over ssh, make sure your remote host fingerprint exists in
your ~/.ssh/known_hosts
file.
Changed in version 2015.8.8: This state module now requires git 1.6.5 (released 10 October 2009) or newer.
salt.states.git.
config_set
(name, value=None, multivar=None, repo=None, user=None, password=None, **kwargs)¶New in version 2014.7.0.
Changed in version 2015.8.0: Renamed from git.config
to git.config_set
. For earlier
versions, use git.config
.
Ensure that a config value is set to the desired value(s)
Set multiple values for the config item
Note
The order matters here, if the same parameters are set but in a different order, they will be removed and replaced in the order specified.
New in version 2015.8.0.
global
is set to True
.Windows only. Required when specifyinguser
. This parameter will be ignored on non-Windows platforms.
New in version 2016.3.4.
If True
, this will set a global git config option
Changed in version 2015.8.0: Option renamed from is_global
to global
. For earlier
versions, use is_global
.
Local Config Example:
# Single value
mylocalrepo:
git.config_set:
- name: user.email
- value: foo@bar.net
- repo: /path/to/repo
# Multiple values
mylocalrepo:
git.config_set:
- name: mysection.myattribute
- multivar:
- foo
- bar
- baz
- repo: /path/to/repo
Global Config Example (User ``foo``):
mylocalrepo:
git.config_set:
- name: user.name
- value: Foo Bar
- user: foo
- global: True
salt.states.git.
config_unset
(name, value_regex=None, repo=None, user=None, password=None, **kwargs)¶New in version 2015.8.0.
Ensure that the named config key is not present
foo\.
would not match all keys in the foo
section, it would be necessary
to use foo\..+
to do so.Regex indicating the values to unset for the matching key(s)
Note
This option behaves differently depending on whether or not all
is set to True
. If it is, then all values matching the regex
will be deleted (this is the only way to delete multiple values
from a multivar). If all
is set to False
, then this state
will fail if the regex matches more than one value in a multivar.
True
, unset all matchesglobal
is set to True
.Windows only. Required when specifyinguser
. This parameter will be ignored on non-Windows platforms.
New in version 2016.3.4.
True
, this will set a global git config optionExamples:
# Value matching 'baz'
mylocalrepo:
git.config_unset:
- name: foo.bar
- value_regex: 'baz'
- repo: /path/to/repo
# Ensure entire multivar is unset
mylocalrepo:
git.config_unset:
- name: foo.bar
- all: True
# Ensure all variables in 'foo' section are unset, including multivars
mylocalrepo:
git.config_unset:
- name: 'foo\..+'
- all: True
# Ensure that global config value is unset
mylocalrepo:
git.config_unset:
- name: foo.bar
- global: True
salt.states.git.
detached
(name, ref, target=None, remote='origin', user=None, password=None, force_clone=False, force_checkout=False, fetch_remote=True, hard_reset=False, submodules=False, identity=None, https_user=None, https_pass=None, onlyif=False, unless=False, **kwargs)¶New in version 2016.3.0.
Make sure a repository is cloned to the given target directory and is
a detached HEAD checkout of the commit ID resolved from ref
.
Windows only. Required when specifyinguser
. This parameter will be ignored on non-Windows platforms.
New in version 2016.3.4.
target
directory exists and is not a git repository, then
this state will fail. Set this argument to True
to remove the
contents of the target directory and clone the repo into it.True
to discard unwritten
changes when checking out.False
a fetch will not be performed and only local refs
will be reachable.If True
a hard reset will be performed before the checkout and any
uncommitted modifications to the working directory will be discarded.
Untracked files will remain in place.
Note
Changes resulting from a hard reset will not trigger requisites.
salt://path/to/identity_file
) to a private key to use for SSH
authentication.onlyif
option returns trueunless
option returns falsesalt.states.git.
latest
(name, rev='HEAD', target=None, branch=None, user=None, password=None, update_head=True, force_checkout=False, force_clone=False, force_fetch=False, force_reset=False, submodules=False, bare=False, mirror=False, remote='origin', fetch_tags=True, depth=None, identity=None, https_user=None, https_pass=None, onlyif=False, unless=False, **kwargs)¶Make sure the repository is cloned to the given directory and is up-to-date.
Address of the remote repository, as passed to git clone
Note
From the Git documentation, there are two URL formats supported for SSH authentication. The below two examples are equivalent:
# ssh:// URL
ssh://user@server/project.git
# SCP-like syntax
user@server:project.git
A common mistake is to use an ssh://
URL, but with a colon
after the domain instead of a slash. This is invalid syntax in
Git, and will therefore not work in Salt. When in doubt, confirm
that a git clone
works for the URL before using it in Salt.
It has been reported by some users that SCP-like syntax is
incompatible with git repos hosted on Atlassian Stash/BitBucket
Server. In these cases, it may be necessary to use ssh://
URLs for SSH authentication.
The remote branch, tag, or revision ID to checkout after clone / before
update. If specified, then Salt will also ensure that the tracking
branch is set to <remote>/<rev>
, unless rev
refers to a tag or
SHA1, in which case Salt will ensure that the tracking branch is unset.
If rev
is not specified, it will be assumed to be HEAD
, and
Salt will not manage the tracking branch at all.
Changed in version 2015.8.0: If not specified, rev
now defaults to the remote repository's
HEAD.
Name of the local branch into which to checkout the specified rev. If not specified, then Salt will not care what branch is being used locally and will just use whatever branch is currently there.
New in version 2015.8.0.
Note
If this argument is not specified, this means that Salt will not change the local branch if the repository is reset to another branch/tag/SHA1. For example, assume that the following state was run initially:
foo_app:
git.latest:
- name: https://mydomain.tld/apps/foo.git
- target: /var/www/foo
- user: www
This would have cloned the HEAD of that repo (since a rev
wasn't specified), and because branch
is not specified, the
branch in the local clone at /var/www/foo
would be whatever the
default branch is on the remote repository (usually master
, but
not always). Now, assume that it becomes necessary to switch this
checkout to the dev
branch. This would require rev
to be
set, and probably would also require force_reset
to be enabled:
foo_app:
git.latest:
- name: https://mydomain.tld/apps/foo.git
- target: /var/www/foo
- user: www
- rev: dev
- force_reset: True
The result of this state would be to perform a hard-reset to
origin/dev
. Since branch
was not specified though, while
/var/www/foo
would reflect the contents of the remote repo's
dev
branch, the local branch would still remain whatever it was
when it was cloned. To make the local branch match the remote one,
set branch
as well, like so:
foo_app:
git.latest:
- name: https://mydomain.tld/apps/foo.git
- target: /var/www/foo
- user: www
- rev: dev
- branch: dev
- force_reset: True
This may seem redundant, but Salt tries to support a wide variety of use cases, and doing it this way allows for the use case where the local branch doesn't need to be strictly managed.
Local system user under which to run git commands. By default, commands are run by the user under which the minion is running.
Note
This is not to be confused with the username for http(s)/SSH authentication.
New in version 0.17.0.
Windows only. Required when specifying user
. This parameter will be
ignored on non-Windows platforms.
New in version 2016.3.4.
If set to False
, then the remote repository will be fetched (if
necessary) to ensure that the commit to which rev
points exists in
the local checkout, but no changes will be made to the local HEAD.
New in version 2015.8.3.
Deprecated since version 2015.8.0: Use force_clone
instead. For earlier Salt versions, force
must be used.
True
to discard unwritten
changes when checking out.target
directory exists and is not a git repository, then
this state will fail. Set this argument to True
to remove the
contents of the target directory and clone the repo into it.If a fetch needs to be performed, non-fast-forward fetches will cause
this state to fail. Set this argument to True
to force the fetch
even if it is a non-fast-forward update.
New in version 2015.8.0.
True
to force a hard-reset to the remote revision in
these cases.True
if the repository is to be a bare clone of the remote
repository.True
if the repository is to be a mirror of the remote
repository. This implies that bare
set to True
, and thus is
incompatible with rev
.Deprecated since version 2015.8.0: Use remote
instead. For earlier Salt versions, remote_name
must be used.
True
, then when a fetch is performed all tags will be fetched,
even those which are not reachable by any branch on the remote.depth: 1
is useful when deploying from a repository
with a long history. Use rev to specify branch. This is not compatible
with tags or revision IDs.Path to a private key to use for ssh URLs. This can be either a single string, or a list of strings. For example:
# Single key
git@github.com:user/repo.git:
git.latest:
- user: deployer
- identity: /home/deployer/.ssh/id_rsa
# Two keys
git@github.com:user/repo.git:
git.latest:
- user: deployer
- identity:
- /home/deployer/.ssh/id_rsa
- /home/deployer/.ssh/id_rsa_alternate
If multiple keys are specified, they will be tried one-by-one in order for each git command which needs to authenticate.
Warning
Unless Salt is invoked from the minion using salt-call
, the
key(s) must be passphraseless. For greater security with
passphraseless private keys, see the sshd(8) manpage for
information on securing the keypair from the remote side in the
authorized_keys
file.
Changed in version 2015.8.7: Salt will no longer attempt to use passphrase-protected keys unless
invoked from the minion using salt-call
, to prevent blocking
waiting for user input.
Changed in version 2016.3.0: Key can now be specified as a SaltStack fileserver URL (e.g.
salt://path/to/identity_file
).
HTTP Basic Auth username for HTTPS (only) clones
New in version 2015.5.0.
HTTP Basic Auth password for HTTPS (only) clones
New in version 2015.5.0.
onlyif
option returns trueunless
option returns falseNote
Clashing ID declarations can be avoided when including different
branches from the same git repository in the same SLS file by using the
name
argument. The example below checks out the gh-pages
and
gh-pages-prod
branches from the same repository into separate
directories. The example also sets up the ssh_known_hosts
ssh key
required to perform the git checkout.
Also, it has been reported that the SCP-like syntax for
gitlab.example.com:
ssh_known_hosts:
- present
- user: root
- enc: ecdsa
- fingerprint: 4e:94:b0:54:c1:5b:29:a2:70:0e:e1:a3:51:ee:ee:e3
git-website-staging:
git.latest:
- name: git@gitlab.example.com:user/website.git
- rev: gh-pages
- target: /usr/share/nginx/staging
- identity: /root/.ssh/website_id_rsa
- require:
- pkg: git
- ssh_known_hosts: gitlab.example.com
git-website-staging:
git.latest:
- name: git@gitlab.example.com:user/website.git
- rev: gh-pages
- target: /usr/share/nginx/staging
- identity: salt://website/id_rsa
- require:
- pkg: git
- ssh_known_hosts: gitlab.example.com
git-website-prod:
git.latest:
- name: git@gitlab.example.com:user/website.git
- rev: gh-pages-prod
- target: /usr/share/nginx/prod
- identity: /root/.ssh/website_id_rsa
- require:
- pkg: git
- ssh_known_hosts: gitlab.example.com
salt.states.git.
mod_run_check
(cmd_kwargs, onlyif, unless)¶Execute the onlyif and unless logic. Return a result dict if:
Otherwise, returns True
salt.states.git.
present
(name, force=False, bare=True, template=None, separate_git_dir=None, shared=None, user=None, password=None)¶Ensure that a repository exists in the given directory
Warning
If the minion has Git 2.5 or later installed, name
points to a
worktree, and force
is set to True
, then the worktree will be
deleted. This has been corrected in Salt 2015.8.0.
Path to the directory
Changed in version 2015.8.0: This path must now be absolute
True
, and if name
points to an existing directory which does
not contain a git repository, then the contents of that directory will
be recursively removed and a new repository will be initialized in its
place.If True
, and a repository must be initialized, then the repository
will be a bare repository.
Note
This differs from the default behavior of git.init
, make sure to set this value to False
if a bare repo is not desired.
If a new repository is initialized, this argument will specify an alternate `template directory`_
New in version 2015.8.0.
If a new repository is initialized, this argument will specify an
alternate $GIT_DIR
New in version 2015.8.0.
Set sharing permissions on git repo. See git-init(1) for more details.
New in version 2015.5.0.
User under which to run git commands. By default, commands are run by the user under which the minion is running.
New in version 0.17.0.
Windows only. Required when specifyinguser
. This parameter will be ignored on non-Windows platforms.
New in version 2016.3.4.