git-plugin

[[git-plugin]] = Git Plugin :toc: macro :toc-title:

[#introduction] == Introduction

image::images/jenkins-and-git.png[Jenkins and Git]

The git plugin provides fundamental git operations for Jenkins projects. It can poll, fetch, checkout, branch, list, merge, tag, and push repositories.

toc::[]

[#changelog] == Changelog in https://github.com/jenkinsci/git-plugin/releases[GitHub Releases]

Release notes are recorded in https://github.com/jenkinsci/git-plugin/releases[GitHub Releases] since July 1, 2019 (git plugin 3.10.1 and later). Prior release notes are recorded in the git plugin repository link:https://github.com/jenkinsci/git-plugin/blob/git-4.7.2/CHANGELOG.adoc[change log].

== Pipelines

The link:https://www.jenkins.io/doc/pipeline/steps/params/scmgit/[`scmGit` parameter] of the git plugin is used with the Pipeline SCM link:https://www.jenkins.io/doc/pipeline/steps/workflow-scm-step/[`checkout` step] to checkout git repositories into Pipeline workspaces. The link:https://www.jenkins.io/redirect/pipeline-snippet-generator[Pipeline Syntax Snippet Generator] guides the user to select checkout options.

The link:https://youtu.be/ai1kf4ihZUo[90 second video clip] below introduces the Pipeline Syntax Snippet Generator and shows how it is used to generate steps for the Jenkins Pipeline.

image:images/pipeline-syntax.png[link=https://youtu.be/ai1kf4ihZUo]

=== Multibranch Pipelines

The git plugin includes a multibranch provider for Jenkins link:https://www.jenkins.io/doc/book/pipeline/multibranch/[Multibranch Pipelines] and for Jenkins link:https://www.jenkins.io/doc/book/pipeline/multibranch/#organization-folders[Organization Folders]. The git plugin multibranch provider is a "base implementation" that uses command line git. Users should prefer the multibranch implementation for their git provider when one is available. Multibranch implementations for specific git providers can use REST API calls to improve the Jenkins experience and add additional capabilities. Multibranch implementations are available for link:https://docs.cloudbees.com/docs/cloudbees-ci/latest/cloud-admin-guide/github-branch-source-plugin[GitHub], link:https://github.com/jenkinsci/bitbucket-branch-source-plugin/blob/master/docs/USER_GUIDE.adoc[Bitbucket], link:https://plugins.jenkins.io/gitlab-branch-source/[GitLab], link:https://plugins.jenkins.io/gitea/[Gitea], and link:https://plugins.jenkins.io/tuleap-git-branch-source/[Tuleap].

The link:https://youtu.be/B_2FXWI6CWg[30 minute video clip] below introduces Multibranch Pipelines.

image:images/multibranch-pipeline.png[link=https://youtu.be/B_2FXWI6CWg]

=== Pipeline examples

The examples below were created with the link:https://www.jenkins.io/redirect/pipeline-snippet-generator[Pipeline Syntax Snippet Generator]. Create your own checkout commands with the link:https://www.jenkins.io/redirect/pipeline-snippet-generator[Pipeline Syntax Snippet Generator] configured for your needs.

==== Checkout with defaults

Checkout from the git plugin source repository using https protocol, no credentials, and the master branch.

[source,groovy]

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

---

==== Checkout with a specific branch

Checkout from the git plugin source repository using https protocol, no credentials, and the stable-3.x branch.

[source,groovy]

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

---

==== Checkout with ssh and a private key credential

Checkout from the git plugin source repository using ssh protocol, ssh private credentials, and the v4.11.x branch. The git plugin supports private key credentials provided by the link:https://plugins.jenkins.io/credentials[Jenkins credentials plugin].

[source,groovy]

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

---

==== Checkout with https and a username/password credential

Checkout from the git plugin source repository using https protocol, username/password credentials, and the v4.9.x branch. The git plugin supports username/password credentials provided by the link:https://plugins.jenkins.io/credentials[Jenkins credentials plugin].

[source,groovy]

checkout scmGit( branches: [[name: 'v4.9.x']], userRemoteConfigs: [[credentialsId: 'my-username-password-id', url: 'https://github.com/jenkinsci/git-plugin.git']])

---

==== Checkout with git large file support enabled

Checkout from the git plugin source repository using https protocol with large file support enabled for the stable-3.x branch.

[source,groovy]

checkout scmGit( branches: [[name: 'stable-3.x']], extensions: [ lfs() ], userRemoteConfigs: [[url: 'https://github.com/jenkinsci/git-plugin.git']])

---

==== Checkout without fetching tags (advanced clone behavior)

Checkout from the git plugin source repository using https with no credentials and without tags. This can save time and disk space when you want to access the repository without considering tags.

[source,groovy]

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

---

==== Checkout with a shallow clone to reduce data traffic

Checkout from the workspace cleanup plugin source repository using https without credentials, a default branch, and a shallow clone. Shallow clone requests a limited number of commits from the tip of the requested branch and may save time, data transfer, and disk space.

[source,groovy]

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

---

==== Checkout with a narrow refspec

Checkout from the workspace cleanup plugin source repository using https without credentials, the master branch, and with a refspec specific to the master branch. This can save time, data transfer, and disk space when you only need to access the references specified by the refspec.

[source,groovy]

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']])

---

==== Checkout and prune stale remote branches

Checkout from the workspace cleanup plugin source repository using https without credentials and with prune tags and prune branches extension enabled. This removes remote tracking branches and tags from the local workspace if they no longer exist on the remote.

[source,groovy]

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

---

==== Wipe out repository before checkout

Remove all files in the workspace before a checkout from the workspace cleanup plugin source repository using https without credentials, a default branch. Ensures a fully fresh workspace.

[source,groovy]

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

---

[#credential-binding] === Git Credentials Binding

The git plugin provides Git Username and Password binding that allows authenticated git operations over HTTP and HTTPS protocols using command line git in a Pipeline job.

The git credential bindings are accessible through the link:https://www.jenkins.io/doc/pipeline/steps/credentials-binding/#withcredentials-bind-credentials-to-variables[`withCredentials`] step of the link:https://plugins.jenkins.io/credentials-binding/[Credentials Binding] plugin. The binding retrieves credentials from the link:https://plugins.jenkins.io/credentials/[Credentials] plugin.

==== Git Username and Password Binding

This binding provides authentication support over HTTP protocol using command line git in a Pipeline job.

Procedure::

. Click the Pipeline Syntax Snippet Generator and choose the withCredentials step, add Git Username and Password binding. . Choose the required credentials and Git tool name, specific to the generated Pipeline snippet.

image:images/git-credentials-usernamepassword-binding-pipline-job.png[Git-Username-and Password-Binding-Pipeline-Job]

Two variable bindings are used, GIT_USERNAME and GIT_PASSWORD, to pass the username and password to sh, bat, and powershell steps inside the withCredentials block of a Pipeline job. The variable bindings are available even if the JGit or JGit with Apache HTTP Client git implementation is being used.

.Shell example

withCredentials([gitUsernamePassword(credentialsId: 'my-credentials-id',
                 gitToolName: 'git-tool')]) {
  sh 'git fetch --all'
}

.Batch example

withCredentials([gitUsernamePassword(credentialsId: 'my-credentials-id',
                 gitToolName: 'git-tool')]) {
  bat 'git submodule update --init --recursive'
}

.Powershell example

withCredentials([gitUsernamePassword(credentialsId: 'my-credentials-id',
                 gitToolName: 'git-tool')]) {
  powershell 'git push'
}

[#configuration] == [[GitPlugin-ProjectConfiguration]]Configuration

[#using-repositories] === Repositories

image:images/git-repository-configuration.png[Repository Configuration]

The git plugin fetches commits from one or more remote repositories and performs a checkout in the agent workspace. Repositories and their related information include:

Repository URL::

The URL of the remote repository. The git plugin passes the remote repository URL to the git implementation (command line or JGit). Valid repository URL's include https, ssh, scp, git, local file, and other forms. Valid repository URL forms are described in the link:https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols#_the_protocols[git documentation].

Credentials::

Credentials are defined using the link:https://plugins.jenkins.io/credentials[Jenkins credentials plugin]. They are selected from a drop-down list and their identifier is stored in the job definition. Refer to > for more details on supported credential types.

Name::

Git uses a short name to simplify user references to the URL of the remote repository. The default short name is origin. Other values may be assigned and then used throughout the job definition to refer to the remote repository.

Refspec::

A refspec maps remote branches to local references. It defines the branches and tags which will be fetched from the remote repository into the agent workspace. + A refspec defines the remote references that will be retrieved and how they map to local references. If left blank, it will default to the normal git fetch behavior and will retrieve all branches. This default behavior is sufficient for most cases. + The default refspec is +refs/heads/*:refs/remotes/REPOSITORYNAME/ where REPOSITORYNAME is the value you specify in the above repository "Name" field. The default refspec retrieves all branches. If a checkout only needs one branch, then a more restrictive refspec can reduce the data transfer from the remote repository to the agent workspace. For example, +refs/heads/master:refs/remotes/origin/master will retrieve only the master branch and nothing else. + The refspec can be used with the > option in the <> to limit the number of remote branches mapped to local references. If "honor refspec on initial clone" is not enabled, then a default refspec for its initial fetch. This maintains compatibility with previous behavior and allows the