{"id":22281230,"url":"https://github.com/jenkinsci/git-client-plugin","last_synced_at":"2025-12-25T03:20:21.380Z","repository":{"id":6998623,"uuid":"8263652","full_name":"jenkinsci/git-client-plugin","owner":"jenkinsci","description":"Git client API for Jenkins plugins","archived":false,"fork":false,"pushed_at":"2025-05-02T18:46:33.000Z","size":7495,"stargazers_count":144,"open_issues_count":13,"forks_count":393,"subscribers_count":113,"default_branch":"master","last_synced_at":"2025-05-02T19:26:45.118Z","etag":null,"topics":["api-plugin","jenkins-security-scan-enabled"],"latest_commit_sha":null,"homepage":"https://plugins.jenkins.io/git-client","language":"Java","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jenkinsci.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":"CONTRIBUTING.adoc","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2013-02-18T07:23:45.000Z","updated_at":"2025-05-02T18:19:50.000Z","dependencies_parsed_at":"2023-02-15T20:16:03.743Z","dependency_job_id":"9f2d9f54-b598-4281-8700-7f74b298faa6","html_url":"https://github.com/jenkinsci/git-client-plugin","commit_stats":{"total_commits":2703,"total_committers":130,"mean_commits":20.79230769230769,"dds":0.4676285608583056,"last_synced_commit":"af5e1cc15ee6e10dc6aa309b9ed50f75b9de0708"},"previous_names":[],"tags_count":165,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fgit-client-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fgit-client-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fgit-client-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fgit-client-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jenkinsci","download_url":"https://codeload.github.com/jenkinsci/git-client-plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254319716,"owners_count":22051072,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-plugin","jenkins-security-scan-enabled"],"created_at":"2024-12-03T16:16:20.277Z","updated_at":"2025-12-25T03:20:21.329Z","avatar_url":"https://github.com/jenkinsci.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"[#git-client-plugin]\n= Git Client Plugin\n:toc: macro\n:toc-title:\n\n[#introduction]\n== Introduction\n\nimage::images/jenkins-and-git.png[Jenkins and Git]\n\nThe git client plugin provides git application programming interfaces (APIs) for Jenkins plugins.\nIt can fetch, checkout, branch, list, merge, and tag repositories.\nRefer to the https://javadoc.jenkins-ci.org/plugin/git-client/[API documentation] for specific API details.\n\nThe https://javadoc.jenkins-ci.org/plugin/git-client/org/jenkinsci/plugins/gitclient/GitClient.html[GitClient interface] provides the primary entry points for git access.\nIt 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+` ).\nIt 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+` ).\nCredential support is provided by the https://plugins.jenkins.io/credentials[Jenkins credentials plugin].\n\ntoc::[]\n\n[#implementations]\n== Implementations\n\nThe git client plugin default implementation requires that https://git-scm.com/downloads[command line git] is installed on the controller and on every agent that will use git.\nCommand line git implementations working with large files should also install https://git-lfs.github.com/[git LFS].\nThe command line git implementation is the canonical implementation of the git interfaces provided by the git client plugin.\n\nCommand line git is *enabled by default* when the git client plugin is installed.\n\n[#jgit]\n=== JGit\n\nThe git client plugin also includes two optional implementations (\"jgit\" and \u003c\u003cjgit-with-apache-http-client,\"jgitapache\"\u003e\u003e) that use https://www.eclipse.org/jgit/[Eclipse JGit], a pure Java implementation of git.\nThe JGit implementation in the git client plugin provides most of the functionality of the command line git implementation.\nWhen the JGit implementation is incomplete, the gap is noted in console logs.\n\nJGit is *disabled by default* when the git client plugin is installed.\n\n[#enabling-jgit]\n=== Enabling JGit\n\nClick the \"*Add Git*\" button in the \"*Tools*\" section under \"*Manage Jenkins*\" to add JGit or JGit with Apache HTTP Client as a git implementation.\n\nimage::images/enable-jgit.png[Enable JGit or JGit with Apache HTTP Client]\n\n=== JGit timeout\n\nThe command line git implementation in the git client plugin provides a timeout setting for many operations like fetch and checkout.\nOperations that take more than the specified time are canceled.\nWhen the timeout is exceeded, the command line git process fails and the git client plugin API operation fails.\n\nThe JGit implementation in the git client plugin uses a different concept of timeout.\nThe JGit timeout is a network level transport timeout rather than a timeout of a higher level JGit operation.\nIf the JGit network transport does not receive a response within the defined timeout, the JGit API call fails.\nThe link:https://javadoc.io/doc/org.eclipse.jgit/org.eclipse.jgit/latest/org.eclipse.jgit/org/eclipse/jgit/transport/Transport.html#setTimeout(int)[JGit javadoc] describes the JGit API.\n\nThe JGit timeout implementation prevents JGit operations from hanging indefinitely when a remote server stops responding.\nIt does not stop a JGit operation if it has executed for more than a specified time.\nThe JGit timeout counter is reset each time a response is received from the remote server during the JGit API call.\nThe command line git timeout counter is set at the start of the command line git call and is not reset during the call.\n\n[#jgit-with-apache-http-client]\n=== JGit with Apache HTTP Client\n\nThe original JGit implementation inside the git client plugin had issues with active directory authentication.\nA workaround was implemented to provide JGit but use Apache HTTP client for authentication.\nThe issue in JGit has now been resolved and delivered in git client plugin releases.\nJGit with Apache HTTP Client continues to delivered to assure compatibility.\n\n[#installing-mingit-for-windows-automatically]\n=== Installing MinGit for Windows Automatically\n\nJenkins can install link:https://gitforwindows.org/mingit[MinGit for Windows] automatically.\nMinGit for Windows is an intentionally minimal, non-interactive distribution of Git for Windows, with third-party applications as its intended audience.\nJenkins is well suited to use MinGit on Windows agents.\n\nimage::images/mingit-for-windows-as-a-tool.png[Configure MinGit for Windows to install automatically]\n\n* Configure a global git tool from \"Manage Jenkins\" \u003e\u003e \"Tools\" with `git` as the `Path to Git executable`\n* Set the label `windows` to limit the tool installer to agents with the `windows` label\n* Set the `Download URL for binary archive` as the URL of your **locally downloaded copy** of the link:https://github.com/git-for-windows/git/releases/[MinGit zip file]\n* Specify `mingw64\\bin\\git.exe` as the `Subdirectory of extracted archive`.\n\nMinGit will be installed on each agent in `tools\\git\\mingw64`.\nThe path to the git executable will be `tools\\git\\mingw64\\bin\\git.exe`.\n\n[#windows-credentials-manager]\n== Windows Credentials Manager\n\nGit for Windows is able to integrate with the Windows Credentials Manager for secure storage of credentials.\nWindows Credentials Manager works very well for interactive users on the Windows desktop.\nWindows Credentials Manager does not work as well for batch processing in the git client plugin.\nIt is best to disable Windows Credentials Manager when installing Git on Jenkins agents running Windows.\n\n[#ssh-host-key-verification]\n== SSH Host Key verification\n\nGit Client plugin provides various options to verify the SSH keys presented by Git repository host servers.\nBy default, Git Client plugin uses the \"Known hosts file\" strategy to verify all host keys using the known_hosts file.\n\nHost key verification strategies include:\n\nAccept first connection::\nRemembers the first host key encountered for each git server and requires that the same host key must be used for later access.\nThis is usually the most convenient setting for administrators while still providing ssh host key verification\n\nKnown hosts file::\nUses the existing `known_hosts` file on the controller and on the agent.\nThis assumes the administrator has already configured this file on the controller and on all agents\n\nManually provided keys::\nProvides a form field where the administrator inserts the host keys for the git repository servers.\nThis works well when a small set of repository servers meet the needs of most users\n\nNo verification::\nDisables all verification of ssh host keys.\n**Not recommended** because it provides no protection from \"man-in-the-middle\" attacks\n\nConfigure the host key verification strategy from \"Manage Jenkins\" \u003e\u003e \"Security\" \u003e\u003e \"Git Host Key Verification Configuration\".\n\nimage::images/ssh-host-key-verification.png[Configure Ssh host key verification]\n\n[NOTE]\n====\nOpenSSH releases prior to link:https://www.openssh.com/txt/release-7.6[OpenSSH 7.6 (released Oct 2017)] do not support the ssh command line argument used to accept first connection.\nRed 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.\nThe \"Git Host Key Verification Configuration\" for those systems cannot use the \"Accept first connection\" strategy with command line git.\n\nThose operating systems are no longer supported by the Jenkins project.\nMore details are available in the link:https://www.jenkins.io/blog/2023/05/30/operating-system-end-of-life/[end of life operating systems blog post].\n\nUsers of those operating systems have the following options:\n\n* Upgrade to a supported operating system\n* Use the \"Manually provided keys\" host key verification strategy and provide host keys for their git hosts\n* Use the \"Known hosts file\" host key verification strategy and provide a known_hosts file on the agents with values for the required hosts\n* Enable JGit and use JGit instead of command line git on agents and controllers with those older OpenSSH versions\n* Switch the repository URL's in job definitions from ssh protocol to https protocol and provide a username / password credential for the clone instead of a private key credential\n* Use the \"No verification\" host key verification strategy (not recommended)\n====\n\n=== Configuration as Code Sample\n\nThe link:https://plugins.jenkins.io/configuration-as-code/[configuration as code plugin] can define the SSH host key verification strategy.\n\nThe \"Accept first connection\" host key verification strategy can be configured like this:\n\n[source,yaml]\n----\nsecurity:\n  gitHostKeyVerificationConfiguration:\n    sshHostKeyVerificationStrategy: \"acceptFirstConnectionStrategy\"\n----\n\nThe \"Known hosts file\" host key verification strategy can be configured like this:\n\n[source,yaml]\n----\nsecurity:\n  gitHostKeyVerificationConfiguration:\n    sshHostKeyVerificationStrategy: \"knownHostsFileVerificationStrategy\"\n----\n\nThe \"Manually provided keys\" host key verification strategy might be configured like this:\n\n[source,yaml]\n----\nsecurity:\n  gitHostKeyVerificationConfiguration:\n    sshHostKeyVerificationStrategy:\n      manuallyProvidedKeyVerificationStrategy:\n        approvedHostKeys: |-\n          bitbucket.org ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIazEu89wgQZ4bqs3d63QSMzYVa0MuJ2e2gKTKqu+UUO\n          github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl\n          gitlab.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAfuCHKVTjquxvt6CM6tdG4SLp1Btn/nOeHHE5UOzRdf\n----\n\nThe \"No verification\" strategy (not recommended) can be configured like this:\n\n[source,yaml]\n----\nsecurity:\n  gitHostKeyVerificationConfiguration:\n    sshHostKeyVerificationStrategy: \"noHostKeyVerificationStrategy\"\n----\n\n[#bug-reports]\n== Bug Reports\n\nReport issues and enhancements with the link:https://www.jenkins.io/participate/report-issue/redirect/#17423[Jenkins issue tracker].\nPlease use the link:https://www.jenkins.io/participate/report-issue/[\"How to Report an Issue\"] guidelines when reporting issues.\n\n[#contributing-to-the-plugin]\n== Contributing to the Plugin\n\nRefer to link:CONTRIBUTING.adoc#contributing-to-the-git-client-plugin[contributing to the plugin] for contribution guidelines.\n\n== Plugin Properties\n\nSome plugin settings are controlled by Java system properties.\nThe properties are often used to override a standard behavior or to revert to previous behavior.\nRefer to link:https://www.jenkins.io/doc/book/managing/system-properties/[Jenkins Features Controlled with System Properties] for more details on system properties and how to set them.\n\ncheckRemoteURL::\nWhen `org.jenkinsci.plugins.gitclient.CliGitAPIImpl.checkRemoteURL` is set to `false` it disables the safety checking of repository URLs.\n+\nDefault is `true` so that repository URL's are rejected if they start with `-` or contain space characters.\n\nforceFetch::\nWhen `org.jenkinsci.plugins.gitclient.CliGitAPIImpl.forceFetch` is set to `false` it allows command line git versions 2.20 and later to not update tags which have already been fetched into the workspace.\n+\nCommand line git 2.20 and later have changed behavior when fetching remote tags that already exist in the repository.\nCommand line git before 2.20 silently updates an existing tag if the remote tag points to a different SHA1 than the local tag.\nCommand 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 `--force` option is passed to `git fetch`.\n+\nDefault is `true` so that newer command line git versions behave the same as older versions.\n\npromptForAuthentication::\nWhen `org.jenkinsci.plugins.gitclient.CliGitAPIImpl.promptForAuthentication` is set to `true` it allows command line git versions 2.3 and later to prompt the user for authentication.\nCommand line git prompting for authentication should be rare, since Jenkins credentials should be managed through the credentials plugin.\n+\nCredential prompting could happen on multiple platforms, but is more common on Windows computers because many Windows agents run from the desktop environment.\nAgents running on the desktop are much less common in Unix environments.\n+\nDefault is `false` so that command line git does not prompt for interactive authentication.\n\nuseCLI::\nWhen `org.jenkinsci.plugins.gitclient.CliGitAPIImpl.useCLI` is set to `false`, it will use JGit as the default implementation instead of command line git.\n+\nDefault is `true` so that command line git is chosen as the default implementation.\n\nuser.name.file.encoding::\nWhen `org.jenkinsci.plugins.gitclient.CliGitAPIImpl.user.name.file.encoding` is set to a non-empty value (like `IBM-1047`) and the agent is running on IBM zOS, the username credentials file is written using that character set.\nThe character sets of other credential files are not changed.\nThe character sets on other operating systems are not changed.\n+\nDefault is empty so that zOS file encoding behaves as it did previously.\n\nuser.passphrase.file.encoding::\nWhen `org.jenkinsci.plugins.gitclient.CliGitAPIImpl.user.passphrase.file.encoding` is set to a non-empty value (like `IBM-1047`) and the agent is running on IBM zOS, the ssh passphrase file is written using that character set.\nThe character sets of other credential files are not changed.\nThe character sets on other operating systems are not changed.\n+\nDefault is empty so that zOS file encoding behaves as it did previously.\n\nuser.password.file.encoding::\nWhen `org.jenkinsci.plugins.gitclient.CliGitAPIImpl.user.password.file.encoding` is set to a non-empty value (like `IBM-1047`) and the agent is running on IBM zOS, the password file is written using that character set.\nThe character sets of other credential files are not changed.\nThe character sets on other operating systems are not changed.\n+\nDefault is empty so that zOS file encoding behaves as it did previously.\n\nuseSETSID::\nWhen `org.jenkinsci.plugins.gitclient.CliGitAPIImpl.useSETSID` is set to `true` and the `setsid` command is available, the git client process on non-Windows computers will be started with the `setsid` command so that they are detached from any controlling terminal.\nMost agents are run without a controlling terminal and the `useSETSID` setting is not needed.\nEnable `useSETSID` only in those rare cases where the agent is running with a controlling terminal.\nIf it is not used in those cases, the agent may block on some authenticated git operations.\n+\nThis setting can be helpful with link:https://plugins.jenkins.io/swarm/[Jenkins swarm agents] and inbound agents started from a terminal emulator.\n+\nDefault is `false` so that `setsid` is not used.\n\n[#changelog]\n== Changelog in https://github.com/jenkinsci/git-client-plugin/releases[GitHub Releases]\n\nRelease notes have been recorded in https://github.com/jenkinsci/git-client-plugin/releases[GitHub] since git client plugin 2.8.1.\nPrior release notes were recorded in the git client plugin repository link:https://github.com/jenkinsci/git-client-plugin/blob/91c7435dffb489c1e0eb0252c7992c61054b822e/CHANGELOG.adoc#changelog-moved-to-github-releases[change log].\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenkinsci%2Fgit-client-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjenkinsci%2Fgit-client-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenkinsci%2Fgit-client-plugin/lists"}