{jenkins-plugin-info:git}

This plugin allows use of Git as a build SCM, including repository browsers for several providers. A recent Git runtime is required (1.7.9 minimum, 1.8.x recommended). Interaction with the Git runtime is performed by the use of the Git Client Plugin, which is only tested on official git client. Use exotic installations at your own risk.

Configuration

Global Settings

In the Configure System page, the Git Plugin provides the following options

Project Configuration

At the project level the Git Plugin is configured by selecting the Git option at the Source Code Management section.

The main section is Repositories where several can be configured. The information to provide include:

The next section is Branches to Build in which several branch specifiers can be provided. For each of these specs, leaving it blank means that all branches will be examined for changes and built. The safest way is to use the refs/heads/<branchName> syntax. This way the expected branch is unambiguous. See the online help for more options.

A Repository Browser can also be configured, which adds links in "changes" views within Jenkins to an external system for browsing the details of those changes. The "Auto" selection attempts to infer the repository browser from other jobs, if supported by the SCM and a job with matching SCM details can be found, though it can also be selected manually.

Finally, the Git Plugin is extensible and the plugin itself as well as external plugins can provide Additional Behaviours to tweak the SCM configuration inside each particular project. Please refer to the online help of each of the additional options for further information.

Bugs

Note: Source code can be found at https://github.com/jenkinsci/git-plugin.

Gotchas

Started by user anonymous
Checkout:workspace / C:\Documents and Settings\Administrator\.hudson\jobs\watir\workspace - hudson.remoting.LocalChannel@1a1f370
Last Build : #4
Checkout:workspace / C:\Documents and Settings\Administrator\.hudson\jobs\watir\workspace - hudson.remoting.LocalChannel@1a1f370
Cloning the remote Git repository
Cloning repository origin
$ git clone -o origin git://github.com/bret/watir.git "C:\Documents and Settings\Administrator\.hudson\jobs\watir\workspace"
Trying next repository
ERROR: Could not clone from a repository
FATAL: Could not clone
hudson.plugins.git.GitException: Could not clone
    at hudson.plugins.git.GitSCM$2.invoke(GitSCM.java:400)
    at hudson.plugins.git.GitSCM$2.invoke(GitSCM.java:358)
    at hudson.FilePath.act(FilePath.java:676)
    at hudson.FilePath.act(FilePath.java:660)
    at hudson.plugins.git.GitSCM.checkout(GitSCM.java:358)
    at hudson.model.AbstractProject.checkout(AbstractProject.java:833)
    at hudson.model.AbstractBuild$AbstractRunner.checkout(AbstractBuild.java:314)
    at hudson.model.AbstractBuild$AbstractRunner.run(AbstractBuild.java:266)
    at hudson.model.Run.run(Run.java:948)
    at hudson.model.Build.run(Build.java:112)
    at hudson.model.ResourceController.execute(ResourceController.java:93)
    at hudson.model.Executor.run(Executor.java:118)

Jenkins, GIT plugin and Windows

Installing the plugin itself works like a charm but configuring the system to work properly under Windows can be a bit tricky. Let´s see the problems you may run into.

Configuring Jenkins to use OpenSSH bundled with msysgit Windows installer

By default, the Jenkins Windows installer sets up Jenkins to run as a service on Windows, which runs as the “Local System account”, NOT your user account. Since the “Local System account” does not have SSH keys or known_hosts set up, “git clone” will hang during the build.  It's possible to keep Jenkins running as the “Local System account” and clone repositories via SSH by making sure that the “Local System account” is set up with a properly configured .ssh directory (i.e. id_rsa, id_rsa.pub, AND known_hosts).  On my Windows 7 x64 box, this directory is C:\Windows\SysWOW64\config\systemprofile\.ssh and in Windows Server 2012 R2 is C:\Windows\system32\config\systemprofile

The first time you connect via SSH to a remote server, you would normally get prompted with the question "Are you sure you want to continue connecting (yes/no)?", which would populate the remote server info in your ~/.ssh/known_hosts.  Even with proper SSH keys set up for the Jenkins user, if you don't have a properly configured ~/.ssh/known_hosts, the build will still hang. 

A quick way to generate this known_hosts file is to copy your Jenkins build SSH keys into C:\Program Files (x86)\Git\.ssh (so that ssh.exe can find them), and run

 c:\>"C:\Program Files (x86)\Git\bin\ssh.exe" -T git@your.git.server

This will populate C:\Program Files (x86)\Git\.ssh\known_hosts and then you can just copy C:\Program Files (x86)\Git\.ssh to C:\Windows\SysWOW64\config\systemprofile\.ssh (the “Local System account” home).

For a more detailed tutorial, see http://computercamp-cdwilson-us.tumblr.com/post/48589650930/jenkins-git-clone-via-ssh-on-windows-7-x64

Adding the server to your trusted list

First of all, if your system/user never connected to the git server, you will have to add the server to your list of trusted servers.
If you get something like this:

The authenticity of host 'GIT SERVER (127.0.0.1)' can't be established.
RSA key fingerprint is 41:d2:d9:31:76:7d:bd:0d:5e:3f:19:db:5d:34:4d:9d.
Are you sure you want to continue connecting (yes/no)? yes

or

The server's host key is not cached in the registry...

Find plink.exe on your system and run:

plink.exe yourgitserver.com

Answer Yes when prompt. You ignore the login part with CTRL+C.
Beware, this is user specific. SO if you run jenkins as user 'John', make sure you login as 'John' before running the previous command.

An alternative option is to add some entries in the registry to HKEY_USERS\.DEFAULT. You will typically run into this problem is you let Jenkins runn as "Local System" but try to add the key to your list while logged in with your user. The registry entries added for a specific user can be found here:

HKEY_CURRENT_USER\Software\SimonTatham\PuTTY\SshHostKeys

Setup your environment variables

General hint: Avoid spaces in environment paths

Mainly, you will need:

Once this is done, make sure you restart your consoles and the jenkins service.

SSH Keys

You will need to generate your SSH keys. The public key will have to be added/installed on the server. Systems like Gitorious, Gitosis or Github make it easy: you will have to simply copy/paste your key. If you need to setup the authentication with a 'simple' server, look for 'authorized_keys' in this document http://www.eng.cam.ac.uk/help/jpmg/ssh/authorized_keys_howto.html

You can read this: http://help.github.com/win-set-up-git/ to see how to generate the keys.

One solution to avoid entering your password (the one you defined in the ssh key in the process above) is to use Pageant.exe. Visit the link below for more details: http://www.ualberta.ca/CNS/RESEARCH/LinuxClusters/pka-putty.html

Note:* future *integration with ssh-credentials-plugin could help

Some windows fun

If you did everything, you should now have a ~/.ssh folder (c:\Users\Bob\.ssh for instance) and this folder contains your keys.
At that point, you may even be able to manually (from the console), clone your repository but Jenkins keeps failing with something like this:

code 128: Cloning into C:\Program Files\Jenkins\jobs\PG3\workspace...
fatal: The remote end hung up unexpectedly

If you run into this issue, you may need to copy the id_rsa* files from your ~./.ssh to another folder.
Find your git.exe and check if there is an .ssh folder there. If so, copy ~./ssh/id_rsa* to this folder and try again.

Push notification from repository

To minimize the delay between a push and a build, it is recommended to set up the post-receive hook in the repository to poke Jenkins when a new push occurs. To do this, add the following line in your hooks/post-receive file, where <URL of the Git repository> is the fully qualified URL you use when cloning this repository.

curl http://yourserver/git/notifyCommit?url=<URL of the Git repository>[&branches=branch1[,branch2]*][&sha1=<commit ID>]

This will scan all the jobs that:

For jobs that meet these conditions, polling will be immediately triggered.  If polling finds a change worthy of a build, a build will in turn be triggered.

This allows a script to remain the same when jobs come and go in Jenkins. Or if you have multiple repositories under a single repository host application (such as Gitosis), you can share a single post-receive hook script with all the repositories. Finally, this URL doesn't require authentication even for secured Jenkins, because the server doesn't directly use anything that the client is sending. It runs polling to verify that there is a change, before it actually starts a build.

When successful, the list of projects that were triggered is returned.

<commit ID is optional. If set, it will trigger a build immediately, without polling for changes. The advantage of this is that you then can have all pushes tested by jenkins, even when developers push at the same time.

Enabling JGit

The git client plugin provides multiple git implementations.  The default git implementation relies on command line git.  Command line git must be installed on each agent.

Administrators can enable a pure java implementation of the git protocol from the "Git" button in "Manage Jenkins" > "Global Tool Configuration".  Implementations are added with the "Add" button.  Once JGit (or JGit apache) has been added, jobs will include a picklist "Git executable" in the git configuration section of the job.

Why Not JGit

As of 1.2.0, the Git plugin uses git-client-plugin for all Git low-level operation. git-client was extracted from git plugin 1.1.x code base, to ensure SoC and allow other plugins (gerrit, git-parameters...) to directly use and contribute to this one when needed.

The git-client plugin 1.0.4 used JGit by default, while still including the command line Git implementation as an alternate implementation.  Initial deployments of the JGit based plugin exposed a number of gaps in the JGit implementation.  Those gaps need to be resolved in the JGit implementation before it can be used as the default implementation. Beginning with git-client-plugin 1.0.5, the command line implementation is the default implementation.

The git-client-plugin provides both command line and JGit implementations for the GitClient interface. Using command line demonstrated (based on large git plugin issue list) to be fragile : running an external process any time some git repository interaction is required introduces file and process leaks, filesystem locks, etc. It's highly system dependent and require user to install and configure adequate tools on all build slaves. It's based on parsing command output, and as such can be broken by any git cli update - legacy code already check git-cli version to detect which option can be used. Once the JGit functionality gaps are closed, we consider JGit will be the way to go. If you want to experiment with the JGit implementation, either configure JGit as an available git installation from the "Manage Jenkins" page, or run Jenkins with -Dorg.jenkinsci.plugins.gitclient.Git.useCLI=false (same for slaves).

Fast Remote Polling

Fast Remote Polling is a feature that uses a speedy 'git ls-remote ...' command to perform the SCM polling action rather than having to a clone and fetch a local repository.

This feature is enabled by default as of versions 2.2+.

In the event that Fast Remote Polling is detected as being not possible (branches to build contains wildcards, etc), polling will fallback to requiring a workspace.

However, it is possible in some environments that Fast Remote Polling will not work due to the fact that it executes on the master and the master may not have a working Git installation.

A workaround for this is to add an additional behavior of Force polling using workspace to all jobs where you want to use SCM polling.

Advanced Features

Using Git, Jenkins and pre-build branch merging

Continuous Integration tools such as Jenkins are useful on projects as they give users early indication that a particular codebase is 'unstable' - and that if a developer checks it out, there will be trouble ahead (they won't be able to work on their own code, because someone else has broken something).

Unfortunately, by the time the build completes, this is often too late (particularly if the build cycle time is very long), as a developer has updated their working copy to the latest, unstable code in the repository and has begun work.

This can lead to the code base remaining unstable as developers tread on each others toes steadily fixing one thing, but breaking something else.

Some environments (e.g. TeamCity) attempt to fix this by making commits into SVN only 'really' happen once they have been tested. These kinds of 'delayed-commits' are problematic, because local SCM tools assume that commits will be immediately available, which can confuse them. In many ways this mechanism is a hack to get around the fact that branch management in SVN is very heavyweight.

Fortunately, with GIT and Jenkins, you can achieve the same 'stable branches' with minimal effort.

Set up your Jenkins project, and leave the 'branch' field in the Git SCM blank. This will cause Jenkins to consider any change on any branch for building.

Next, pick a particular branch name as the integration target in the 'Advanced' section - (e.g. 'master', or 'stable'), and select 'Merge before build'.

Select 'Push GIT tags back to origin repository' from the post-build actions (this is required to update your centralised git repo with the results of the build).

Now, developers should never commit directly to your integration branch (the 'master' or 'stable'). Instead, they should either use feature branches, or create new remote branches on commit (e.g : "git push origin HEAD:refs/heads/myNewFeature"). You could also set up your GIT repository to only accept commits onto the integration branch from Jenkins.

You're done. Commits should now be automatically merged with the integration branch (they will fail if they do not merge cleanly), and built. If the build succeeds, the result of the merge will be pushed back to the remote git repository.

Using Extra Repositories

Since GIT is a Distributed SCM, it is possible in the Advanced section to specify multiple repositories. You may wish to do this to, for example, pull all in-progress work from individual developers machines, and pre-test them before they are committed to a centralised repository - this way developers may get an early warning that a branch in progress may not be stable.

The GIT plugin will make reasonable attempts to try and pull submodule states from distributed repositories, with the proviso that this feature is not currently well supported within GIT itself.

Autogenerate submodule configurations

A common development pattern for many users is the use of a 'superproject' that aggregates a number of submodules. For example, ProjectA may have ComponentA, ComponentB and ComponentC. ComponentA is a shared library, and is set to use a particular revision (maybe on a branch called 'ProjectA' in case there are any changes). Usually, any changes to the project configuration require a commit to the ProjectA superproject.

However - there could be other changes happening on other branches of ComponentA (say to the development of the next version). Without someone generating commits into ProjectA to test these, any regressions or incompatibilities may be missed.

The autogenerate submodule configurations feature will create commits into ProjectA for all possible combinations of the branches present in the submodules that the project uses.

Recursive submodules

The GIT plugin supports repositories with submodules which in turn have submodules themselves. This must be turned on though: in Job Configuration -> Section Source Code Management, Git -> Advanced Button (under Branches to build) -> Recursively update submodules.

Environment variables

The git plugin sets several environment variables you can use in your scripts:

Change Log

Version 4.0.0-beta4 (not released)

Version 4.0.0-beta3 (July 4, 2018)

Version 4.0.0-beta2 (June 4, 2018)

Version 4.0.0-beta1 (May 28, 2018)

Version 3.9.1 (June 4, 2018)

Version 3.9.0 (May 12, 2018)

Version 3.8.0 (February 26, 2018)

Version 3.7.0 (December 21, 2017)

Version 3.6.4 (November 5, 2017)

Version 3.6.3 (October 26, 2017)

Version 3.6.2 (October 23, 2017)

Version 3.6.1 (October 23, 2017)

Version 3.6.0 (October 2, 2017)

Version 3.5.1 (August 5, 2017)

Version 3.5.0 (July 28, 2017)

Version 3.4.1 (July 18, 2017)

Version 3.4.0 (July 17, 2017)

Version 3.3.2 (July 10, 2017)

Version 3.3.1 (June 23, 2017)

Version 3.3.0 (April 21, 2017)

Version 3.2.0 (March 28, 2017)

Version 3.1.0 (March 4, 2017)

Version 3.0.5 (February 9, 2017)

Version 2.6.5 (February 9, 2017)

Version 3.0.4 (February 2, 2017)

Version 2.6.4 (February 2, 2017)

Version 3.0.3 (January 16, 2017)

Version 2.6.3 (SKIPPED)

Version 3.0.2 (January 16, 2017)

Version 2.6.2 (January 16, 2017)

Version 3.0.2-beta-1 (December 16, 2016)

Version 2.6.2-beta-1 (December 16, 2016)

Version 3.0.1 (November 18, 2016)

Version 2.6.1 (November 9, 2016)

Version 3.0.0 (September 10, 2016)

Version 2.6.0 (September 2, 2016)

Version 2.5.3 (July 30, 2016)

Version 3.0.0-beta2 (July 6, 2016)

Version 2.5.2 (July 4, 2016)

Version 2.5.1 (July 2, 2016)

Version 2.5.0 (June 19, 2016) - Submodule authentication has moved into git 3.0.0-beta

Version 3.0.0-beta1 (June 15, 2016)

Version 2.5.0-beta5 (April 19, 2016)

Version 2.4.4 (March 24, 2016)

Version 2.4.3 (March 19, 2016)

Version 2.4.2 (February 1, 2016)

Version 2.4.1 (December 26, 2015)

Version 2.5.0-beta3 (November 12, 2015)

Version 2.5.0-beta2 (November 8, 2015)

Version 2.5.0-beta1 (November 4, 2015)

Version 2.4.0 (July 18, 2015)

Version 2.3.5 (February 18, 2015)

Version 2.3.4 (January 8, 2015)

Version 2.2.12 (January 8, 2015)

Version 2.3.3 (January 6, 2015)

Version 2.2.11 (January 6, 2015)

Version 2.3.2 (December 19, 2014)

Version 2.2.10 (December 19, 2014)

Version 2.3.1 (November 29, 2014)

Version 2.2.9 (November 23, 2014)

Version 2.2.8 (November 12, 2014)

Version 2.3 (November 10, 2014)

Version 2.3-beta-4 (October 29, 2014)

Version 2.2.7 (October 8, 2014)

Version 2.3-beta-3 (October 8, 2014)

Version 2.2.6 (September 20, 2014)

Version 2.3-beta-2 (September 3, 2014)

Version 2.2.5 (August 15, 2014)

Version 2.2.4 (August 2, 2014)

Version 2.2.3 (July 31, 2014)

Version 2.3-beta-1 (June 16, 2014)

Version 2.2.2 (June 24, 2014)

Version 2.2.1 (April 12, 2014)

Version 2.2.0 (April 4, 2014)

Version 2.1.0 (March 31, 2014)

Version 2.0.4 (March 6, 2014)

Version 2.0.3 (February 21, 2014)

Version 2.0.2 (February 20, 2014)

Version 2.0.1 (January 8, 2014)

Version 2.0 (October 22, 2013) - just in time for JUC :P

Version 1.5.0 (August 28, 2013)

Version 1.4.0 (May 13, 2013)

Version 1.3.0 (March 12, 2013)

Version 1.2.0 (February 20, 2013)

Version 1.1.29 (February 17, 2013)

Version 1.1.27 (February 17, 2013)

GitAPI cleanup

Long term plan is to replace GitAPI cli-based implementation with a pure java (JGit) one, so that plugin is not system dependent.

Version 1.1.26 (November 13, 2012)

Version 1.1.25 (October 13, 2012)

Version 1.1.24 (September 27, 2012)

Version 1.1.23 (September 3, 2012)

Version 1.1.22 (August 8, 2012)

Version 1.1.21 (July 10, 2012)

Version 1.1.20 (June 25, 2012)

Version 1.1.19 (June 8, 2012)

Version 1.1.18 (April 27, 2012)

Version 1.1.17 (April 9, 2012)

Version 1.1.16 (February 28, 2012)

Version 1.1.15 (December 27, 2011)

Version 1.1.14 (November 30, 2011)

Version 1.1.13 (November 24, 2011)

Version 1.1.12 (August 5, 2011)

Version 1.1.11 (July 22, 2011)

Version 1.1.10 (July 15, 2011)

Version 1.1.9 (May 16, 2011)

Version 1.1.8 (May 6, 2011)

Version 1.1.7 (May 4, 2011)

Version 1.1.6 (March 8, 2011)

Version 1.1.5 (February 14, 2011)

Version 1.1.4 (December 4, 2010)

Version 1.1.3 (November 8, 2010)

Version 1.1.2 (November 8, 2010)

Version 1.1.1 (November 5, 2010)

Version 1.1 (September 21, 2010)

Version 1.0.1 (August 9, 2010)

Version 1.0 (July 29, 2010)

Version 0.9.2 (June 22, 2010)

Version 0.9.1 (June 22, 2010)

Version 0.9 (June 17, 2010)

Version 0.8.2

Version 0.7.3

Version 0.5

Version 0.4 (never released)

Version 0.3

Version 0.2

Version 0.1