The git client plugin provides git application programming interfaces (APIs) for Jenkins plugins. It can fetch, checkout, branch, list, merge, and tag repositories. Refer to the API documentation for specific API details.
The GitClient interface provides the primary entry points for git access. It supports username / password credentials for git repository access with HTTP and HTTPS protocols (for example, https://github.com/jenkinsci/git-client-plugin or https://git.example.com/your-repo.git ). It supports private key credentials for git repository access with SSH protocol (for example, git@github.com:jenkinsci/git-client-plugin.git or ssh://git@github.com/jenkinsci/git-client-plugin.git ). Credential support is provided by the Jenkins credentials plugin.
The git client plugin default implementation requires that command line git is installed on the controller and on every agent that will use git. Command line git implementations working with large files should also install git LFS. The command line git implementation is the canonical implementation of the git interfaces provided by the git client plugin.
Command line git is enabled by default when the git client plugin is installed.
The git client plugin also includes two optional implementations ("jgit" and "jgitapache") that use Eclipse JGit, a pure Java implementation of git. The JGit implementation in the git client plugin provides most of the functionality of the command line git implementation. When the JGit implementation is incomplete, the gap is noted in console logs.
JGit is disabled by default when the git client plugin is installed.
Click the "Add Git" button in the "Tools" section under "Manage Jenkins" to add JGit or JGit with Apache HTTP Client as a git implementation.
The command line git implementation in the git client plugin provides a timeout setting for many operations like fetch and checkout. Operations that take more than the specified time are canceled. When the timeout is exceeded, the command line git process fails and the git client plugin API operation fails.
The JGit implementation in the git client plugin uses a different concept of timeout. The JGit timeout is a network level transport timeout rather than a timeout of a higher level JGit operation. If the JGit network transport does not receive a response within the defined timeout, the JGit API call fails. The JGit javadoc describes the JGit API.
The JGit timeout implementation prevents JGit operations from hanging indefinitely when a remote server stops responding. It does not stop a JGit operation if it has executed for more than a specified time. The JGit timeout counter is reset each time a response is received from the remote server during the JGit API call. The command line git timeout counter is set at the start of the command line git call and is not reset during the call.
The original JGit implementation inside the git client plugin had issues with active directory authentication. A workaround was implemented to provide JGit but use Apache HTTP client for authentication. The issue in JGit has now been resolved and delivered in git client plugin releases. JGit with Apache HTTP Client continues to delivered to assure compatibility.
Jenkins can install MinGit for Windows automatically. MinGit for Windows is an intentionally minimal, non-interactive distribution of Git for Windows, with third-party applications as its intended audience. Jenkins is well suited to use MinGit on Windows agents.
-
Configure a global git tool from "Manage Jenkins" >> "Tools" with
gitas thePath to Git executable -
Set the label
windowsto limit the tool installer to agents with thewindowslabel -
Set the
Download URL for binary archiveas the URL of your locally downloaded copy of the MinGit zip file -
Specify
mingw64\bin\git.exeas theSubdirectory of extracted archive.
MinGit will be installed on each agent in tools\git\mingw64. The path to the git executable will be tools\git\mingw64\bin\git.exe.
Git for Windows is able to integrate with the Windows Credentials Manager for secure storage of credentials. Windows Credentials Manager works very well for interactive users on the Windows desktop. Windows Credentials Manager does not work as well for batch processing in the git client plugin. It is best to disable Windows Credentials Manager when installing Git on Jenkins agents running Windows.
Git Client plugin provides various options to verify the SSH keys presented by Git repository host servers. By default, Git Client plugin uses the "Known hosts file" strategy to verify all host keys using the known_hosts file.
Host key verification strategies include:
- Accept first connection
-
Remembers the first host key encountered for each git server and requires that the same host key must be use for later access. This is usually the most convenient setting for administrators while still providing ssh host key verification
- Known hosts file
-
Uses the existing
known_hostsfile on the controller and on the agent. This assumes the administrator has already configured this file on the controller and on all agents - Manually provided keys
-
Provides a form field where the administrator inserts the host keys for the git repository servers. This works well when a small set of repository servers meet the needs of most users
- No verification
-
Disables all verification of ssh host keys. Not recommended because it provides no protection from "man-in-the-middle" attacks
Configure the host key verification strategy from "Manage Jenkins" >> "Security" >> "Git Host Key Verification Configuration".
|
Note
|
OpenSSH releases prior to OpenSSH 7.6 (released Oct 2017) do not support the ssh command line argument used to accept first connection. Red Hat Enterprise Linux 7, CentOS 7, Oracle Linux 7, Scientific Linux 7, Amazon Linux 2, Debian 9, and Ubuntu 16.04 all deliver OpenSSH releases older than OpenSSH 7.6. The "Git Host Key Verification Configuration" for those systems cannot use the "Accept first connection" strategy with command line git. Those operating systems are no longer supported by the Jenkins project. More details are available in the end of life operating systems blog post. Users of those operating systems have the following options:
|
The configuration as code plugin can define the SSH host key verification strategy.
The "Accept first connection" host key verification strategy can be configured like this:
security:
gitHostKeyVerificationConfiguration:
sshHostKeyVerificationStrategy: "acceptFirstConnectionStrategy"
The "Known hosts file" host key verification strategy can be configured like this:
security:
gitHostKeyVerificationConfiguration:
sshHostKeyVerificationStrategy: "knownHostsFileVerificationStrategy"
The "Manually provided keys" host key verification strategy might be configured like this:
security:
gitHostKeyVerificationConfiguration:
sshHostKeyVerificationStrategy:
manuallyProvidedKeyVerificationStrategy:
approvedHostKeys: |-
bitbucket.org ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIazEu89wgQZ4bqs3d63QSMzYVa0MuJ2e2gKTKqu+UUO
github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl
gitlab.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAfuCHKVTjquxvt6CM6tdG4SLp1Btn/nOeHHE5UOzRdf
The "No verification" strategy (not recommended) can be configured like this:
security:
gitHostKeyVerificationConfiguration:
sshHostKeyVerificationStrategy: "noHostKeyVerificationStrategy"
Report issues and enhancements with the Jenkins issue tracker. Please use the "How to Report an Issue" guidelines when reporting issues.
Refer to contributing to the plugin for contribution guidelines.
Some plugin settings are controlled by Java system properties. The properties are often used to override a standard behavior or to revert to previous behavior. Refer to Jenkins Features Controlled with System Properties for more details on system properties and how to set them.
- checkRemoteURL
-
When
org.jenkinsci.plugins.gitclient.CliGitAPIImpl.checkRemoteURLis set tofalseit disables the safety checking of repository URLs.Default is
trueso that repository URL’s are rejected if they start with-or contain space characters. - forceFetch
-
When
org.jenkinsci.plugins.gitclient.CliGitAPIImpl.forceFetchis set tofalseit allows command line git versions 2.20 and later to not update tags which have already been fetched into the workspace.Command line git 2.20 and later have changed behavior when fetching remote tags that already exist in the repository. Command line git before 2.20 silently updates an existing tag if the remote tag points to a different SHA1 than the local tag. Command line git 2.20 and later do not update an existing tag if the remote tag points to a different SHA1 than the local tag unless the
--forceoption is passed togit fetch.Default is
trueso that newer command line git versions behave the same as older versions. - promptForAuthentication
-
When
org.jenkinsci.plugins.gitclient.CliGitAPIImpl.promptForAuthenticationis set totrueit allows command line git versions 2.3 and later to prompt the user for authentication. Command line git prompting for authentication should be rare, since Jenkins credentials should be managed through the credentials plugin.Credential prompting could happen on multiple platforms, but is more common on Windows computers because many Windows agents run from the desktop environment. Agents running on the desktop are much less common in Unix environments.
Default is
falseso that command line git does not prompt for interactive authentication. - useCLI
-
When
org.jenkinsci.plugins.gitclient.CliGitAPIImpl.useCLIis set tofalse, it will use JGit as the default implementation instead of command line git.Default is
trueso that command line git is chosen as the default implementation. - user.name.file.encoding
-
When
org.jenkinsci.plugins.gitclient.CliGitAPIImpl.user.name.file.encodingis set to a non-empty value (likeIBM-1047) and the agent is running on IBM zOS, the username credentials file is written using that character set. The character sets of other credential files are not changed. The character sets on other operating systems are not changed.Default is empty so that zOS file encoding behaves as it did previously.
- user.passphrase.file.encoding
-
When
org.jenkinsci.plugins.gitclient.CliGitAPIImpl.user.passphrase.file.encodingis set to a non-empty value (likeIBM-1047) and the agent is running on IBM zOS, the ssh passphrase file is written using that character set. The character sets of other credential files are not changed. The character sets on other operating systems are not changed.Default is empty so that zOS file encoding behaves as it did previously.
- user.password.file.encoding
-
When
org.jenkinsci.plugins.gitclient.CliGitAPIImpl.user.password.file.encodingis set to a non-empty value (likeIBM-1047) and the agent is running on IBM zOS, the password file is written using that character set. The character sets of other credential files are not changed. The character sets on other operating systems are not changed.Default is empty so that zOS file encoding behaves as it did previously.
- useSETSID
-
When
org.jenkinsci.plugins.gitclient.CliGitAPIImpl.useSETSIDis set totrueand thesetsidcommand is available, the git client process on non-Windows computers will be started with thesetsidcommand so that they are detached from any controlling terminal. Most agents are run without a controlling terminal and theuseSETSIDsetting is not needed. EnableuseSETSIDonly in those rare cases where the agent is running with a controlling terminal. If it is not used in those cases, the agent may block on some authenticated git operations.This setting can be helpful with Jenkins swarm agents and inbound agents started from a terminal emulator.
Default is
falseso thatsetsidis not used.
Changelog in GitHub Releases
Release notes have been recorded in GitHub since git client plugin 2.8.1. Prior release notes were recorded in the git client plugin repository change log.