git-plugin and the checkout options nobody discovers until they need them

The plugin that other plugins depend on

The git plugin provides fundamental git operations for Jenkins projects, and the list is the whole scope of it: it can poll, fetch, checkout, branch, list, merge, tag and push repositories.

That is a small description for something this central. The plugin is published on the Jenkins plugin site at plugins.jenkins.io/git, and the real reason to know about it is that the scmGit parameter used with the Pipeline checkout step comes from it. If you write a Jenkinsfile that checks out code, this plugin is the thing providing the parameter you are passing.

The plugin is MIT licensed, and the repository is a standard Maven Java project with a pom.xml, a Jenkinsfile for its own build, a .mvn directory and a .sonarcloud.properties file for SonarCloud analysis. The source lives under src/.

The audience is Jenkins administrators and pipeline authors. Most of them will arrive here because something in a Jenkinsfile is failing rather than because they chose the plugin, which is why the configuration examples matter more here than in most projects.

scmGit in a Pipeline, and the snippet generator

The Pipeline surface is the scmGit parameter combined with the checkout step, and the README points at the Pipeline Syntax Snippet Generator as the way to produce the code rather than write it from memory.

The simplest form checks out a branch over https with no credentials:

checkout scmGit(
    branches: [[name: 'master']],
    userRemoteConfigs: [[url: 'https://github.com/jenkinsci/git-plugin.git']])

Credentials go in through the credentialsId key rather than in the URL, and the plugin supports private key credentials and username/password credentials provided by the Jenkins credentials plugin. A checkout over ssh with a private key looks like this:

checkout scmGit(
    branches: [[name: 'v4.11.x']],
    userRemoteConfigs: [[credentialsId:  'my-ssh-private-key-id',
        url: 'ssh://github.com/jenkinsci/git-plugin.git']])

The same shape works over https with a username and password credential, using a credentialsId in the same position.

The generator is worth taking seriously. Writing these blocks by hand means getting the nested list structure right, where a mistake in the bracket nesting produces a configuration that parses but does not mean what you intended. The generator produces the structure, and the README's examples are there to show what the options do.

cloneOption is where the build time goes

The extensions list is the part of the configuration that changes how long a checkout takes, and the README gives four separate examples for it.

A shallow clone requests a limited number of commits from the tip of the requested branch, and the README says it may save time, data transfer and disk space:

checkout scmGit(
    branches: [[name: '*/master']],
    extensions: [ cloneOption(shallow: true) ],
    userRemoteConfigs: [[url: 'https://github.com/jenkinsci/ws-cleanup-plugin.git']])

A narrow refspec is the other half of the same idea. Setting honorRefspec means only the references named in the refspec are fetched, with the refspec given as a key inside userRemoteConfigs:

checkout scmGit(
    branches: [[name: '*/master']],
    extensions: [ cloneOption(honorRefspec: true) ],
    userRemoteConfigs: [[refspec: '+refs/heads/master:refs/remotes/origin/master',
        url: 'https://github.com/jenkinsci/ws-cleanup-plugin.git']])

And noTags skips tags entirely, which the README explains can save time and disk space when you want the repository without considering tags:

checkout scmGit(
    branches: [[name: 'master']],
    extensions: [ cloneOption(noTags: true) ],
    userRemoteConfigs: [[url: 'https://github.com/jenkinsci/git-plugin.git']])

These three are the difference between a checkout that pulls the entire history of a project with a decade of commits and one that pulls what the build actually needs. If your builds are slow and the repository is large, this is usually where the time is.

Git large file support is the other extension, enabled with lfs(), and there is a prune extension that removes remote tracking branches and tags from the local workspace when they no longer exist on the remote.

The multibranch provider is a base implementation, and that is the point

The git plugin includes a multibranch provider for Jenkins Multibranch Pipelines and for Organization Folders, and the README is unusually direct about its limits. It calls the git plugin multibranch provider a base implementation that uses command line git, and it says users should prefer the multibranch implementation for their git provider when one is available.

The reasoning follows. Multibranch implementations for specific git providers can use REST API calls to improve the Jenkins experience and add additional capabilities, which a command-line-git-based provider cannot do. The listed alternatives cover GitHub, Bitbucket, GitLab, Gitea and Tuleap, each with its own plugin page.

This is a design decision, not a deficiency. The base implementation works with any git host because it only needs the git binary, which means a new host or a self-hosted Git server works without waiting for a provider plugin. The cost is that provider-specific features, like pull request status, commit status checks or a richer branch listing, are not available from the base provider.

So the practical decision is whether your pipeline needs those features. If a pipeline explicitly checks out a known repository, the base provider is not involved at all. If you rely on Jenkins indexing every branch of a repository and building each one, the provider plugin for your host is the better choice.

Releases, changelog and how upgrades are tracked

The repository is not archived and the last push was on 2026-10-16, so the plugin is actively worked on. The tagged releases are 5.11.0 from 2026-10-11, 5.10.1 from 2026-03-25 and 5.10.0 from 2026-02-09.

The changelog is unusual and worth knowing about. Release notes have been recorded in GitHub Releases since July 1, 2019, which the README dates to git plugin 3.10.1 and later. Prior release notes live in the repository's own change log file, at a link pinned to the git-4.7.2 tag. So there is a split history: a modern release stream on GitHub and an older changelog in the tree, and the boundary is a specific date and a specific version rather than a vague rule.

That split means a reader looking for what changed in a recent upgrade will not find it in the repository, and a reader looking for the older history has to follow a link to a tagged file rather than read the current one.

The versioning deserves a note too. The recent release numbers are 5.x, while the Pipeline examples in the README still use branch names such as v4.11.x and v4.9.x as examples of what to check out. Those are example branches, not the plugin's own version, but on a first read the mixture of numbers is confusing. The version that matters for an upgrade is the plugin version in the Jenkins plugin manager.

What the plugin does not cover

The feature list is short enough that the omissions are as informative as the inclusions.

The operations named are poll, fetch, checkout, branch, list, merge, tag and push. There is no mention of submodules, of worktrees, of pull request creation, of code review integration, of commit signing, or of a subversion or mercurial equivalent, since this plugin is git-specific and there is a separate plugin for each of those.

There is also nothing about repository hosting. The plugin talks to git over the protocols git speaks. Whether a checkout uses a personal access token, an SSH key, a credential helper or an agent is a decision made by the credential plugin and the git configuration on the agent, not by this one.

The one structural limitation worth flagging is the command line dependency. The base multibranch provider uses command line git, so the git binary has to exist on the agent where the build runs. The README does not describe what happens when it is absent, and on a containerised agent image that is a real deployment detail rather than a formality.

Finally, the checkout examples assume public https URLs for most cases and show credentials through the credentials plugin. There is no discussion in the README of host key verification, of a known_hosts strategy for ssh checkouts, or of how a self-hosted git server with a self-signed certificate is expected to be handled, which are the questions you will have to answer from the credentials plugin's own documentation.

Editorial conclusion

git-plugin is a good fit for any Jenkins installation that needs to work with Git, because it is the plugin the scmGit parameter and the checkout step depend on, so it is rarely a choice you make. It is a poor fit if your builds need provider-specific features, since the multibranch provider it ships is a base implementation that uses the git command line, and the README recommends the provider-specific multibranch plugins where one exists for GitHub, Bitbucket, GitLab, Gitea or Tuleap. Before adopting, decide whether your pipeline needs a shallow clone or a narrow refspec, because the cloneOption extension covers both and is the difference between a fast checkout and a slow one on a large repository, and confirm that the multibranch plugin for your git host is installed if you rely on branch indexing rather than explicit checkouts.

Frequently asked questions

Official sources

1. jenkinsci/git-plugin on GitHub
2. License: MIT
3. Project website
4. README
5. Releases