GitHub Plugin

Skip to end of metadata
Go to start of metadata

Plugin Information

Plugin ID github Changes In Latest Release
Since Latest Release
Latest Release
Latest Release Date
Required Core
Dependencies
1.8
Aug 27, 2013
1.445
multiple-scms (version:0.2, optional)
github-api (version:1.42)
git (version:1.1.17)
Source Code
Issue Tracking
Maintainer(s)
GitHub
Open Issues
Kohsuke Kawaguchi (id: kohsuke)
Stefan Saasen (id: juretta)
Usage Installations 2013-Apr 7397
2013-May 7718
2013-Jun 7860
2013-Jul 8341
2013-Aug 8706
2013-Sep 8852
2013-Oct 9448
2013-Nov 9415
2013-Dec 9402
2014-Jan 10096
2014-Feb 10583
2014-Mar 11107

Github Plugin

This plugin integrates Jenkins with Github projects.

The plugin currently has two major functionalities:

  • Create hyperlinks between your Jenkins projects and GitHub
  • Trigger a job when you push to the repository by groking HTTP POSTs from post-receive hook and optionally auto-managing the hook setup.

Hyperlinks between changes

The Github plugin decorates Jenkins "Changes" pages to create links to your Github commit and issue pages. It adds a sidebar link that links back to the Github project page.

When creating a job, specify that is connects to git. Under "Github project", put in: git@github.com:Person/Project.git Under "Source Code Management" select Git, and put in git@github.com:Person/Project.git

Trigger a build when a change is pushed to GitHub

To use this feature:

Step 1. Go to the global configuration and choose the mode in which Jenkins manages post-receive hooks in your GitHub repositories.

  • Automatic Mode: in this mode, Jenkins will automatically add/remove hook URLs to GitHub based on the project configuration in the background. You'll specify GitHub user names and passwords so that Jenkins can login as you to do this, and yes, we need your password and not API token because GitHub doesn't have an API for managing post-commit hooks.
  • Manual Mode: in this mode, you'll be responsible for registering the hook URLs to GitHub. Click the icon to see the URL in Jenkins that receives the post-commit POSTs.

Step 2. Open "Manage Jenkins > Configure Global Security" page and make sure that "Grant READ permissions for /github-webhook" is enabled in the "GitHub Authorization Settings" section

Step 3. Once that configuration is done, go to the project config of each job you want triggered automatically and simply check "Build when a change is pushed to GitHub" under "Build Triggers". With this, every new push to the repository automatically triggers a new build.

Note that there's only one URL and it receives all post-receive POSTs for all your repositories. The server side of this URL is smart enough to figure out which projects need to be triggered, based on the submission.

Security Implications

This plugin requires that you have an HTTP URL reachable from GitHub, which means it's reachable from the whole internet. So it is implemented carefully with the possible malicious fake post-receive POSTS in mind. To cope with this, upon receiving a POST, Jenkins will talk to GitHub to ensure the push was actually made.

Jenkins inside a firewall

In case your Jenkins run inside the firewall and not directly reachable from the internet, this plugin lets you specify an arbitrary endpoint URL as an override in the automatic mode. The plugin will assume that you've set up reverse proxy or some other means so that the POST from GitHub will be routed to the Jenkins.

Trouble-shooting hooks

If you set this up but build aren't triggered, check the following things:

  • Click the "admin" button on the GitHub repository in question and make sure post-receive hooks are there.
    • If it's not there, make sure you have proper credential set in the Jenkins system config page.
    • Also, enable logging for the class name com.cloudbees.jenkins.GitHubPushTrigger and you'll see the log of Jenkins trying to install a post-receive hook.
  • enable logging for the class name com.cloudbees.jenkins.GitHubWebHook. Click "Test hook" button from the GitHub UI and see if you see GitHubWebBook receive a payload.
Documentation Todo:
  • How does this relate to the normal Git plugin? Is it also needed, or does it replace it? Does it offer the same functionality? Why is this even needed?
  • Does this only work with the public github or also private github instances?
  • Maybe also document some if this plugins limitations

Possible Issues between Jenkins and GitHub

Windows:

  • In windows, Jenkins will use the the SSH key of the user it is running as, which is located in the %USERPROFILE%\.ssh folder ( on XP, that would be C:\Documents and Settings\USERNAME\.ssh, and on 7 it would be C:\Users\USERNAME\.ssh). Therefore, you need to force Jenkins to run as the user that has the SSH key configured. To do that, right click on My Computer, and hit "Manage". Click on "Services". Go to Jenkins, right click, and select  "Properties". Under the "Log On" tab, choose the user Jenkins will run as, and put in the username and password (it requires one). Then restart the Jenkins service by right clicking on Jenkins (in the services window), and hit "Restart".
  • Jenkins does not support passphrases for SSH keys. Therefore, if you set one while running the initial Github configuration, rerun it and don't set one.

Change Log

Version 1.7 (Jul 7, 2013)
  • Add the name of the user who pushed to Github into the log (pull #17).
  • Recognize GitHub repository URLs that doesn't end with ".git"
  • Got rid of API token and added OAuth token for interacting with GitHub.
  • Webhook support is no longer a pre-requisite for commit status notification (issue #18165)
Version 1.4 (Jun 13, 2012)
  • Removed GitHub V2 API dependency
Version 1.3 (May 31, 2012)
  • Improved to use the new Jenkins hook type available in GitHub
  • Change GitHubPushCause to extend from SCMTriggerCause (pull #15).
Version 1.2 (Mar 13, 2012)
  • Refactored to enable GitHub SQS plugin (pull #13).
Version 1.1 (Feb 11, 2012)
  • URL normalisation corrupts urls where the project name legitimately ends in 'tree/' (pull #10).
  • Global configuration not saved since Jenkins 1.445 (issue #12487).
  • Also trigger jobs with GitHub repositories configured via MultipleSCMs plugin (pull #12).
  • Match git http:// urls which don't container a username@host since these are valid.
Version 1.0 (Jan 11, 2012)
  • the post-receive hook handling was not poking read-protected projects.
Version 0.9 (Jan 4, 2012)
  • Fixed a bug in handling organization's private repository pull #4
  • Updated to use a newer version of the github-api library.
Version 0.7 (Aug 27, 2011)
  • Supported ssh-based access to GitHub. pull #4
  • Fixed a bug in GitHub repository pattern matching that didn't allow "." in the name pull #3
Version 0.6 (Jul 21, 2011)
  • Added JGit explicitly to improve interaction with the Git plugin
Version 0.5 (Jun 10, 2011)
  • Added support for post-receive trigger
Version 0.4 (Feb 14, 2011)
  • Remove unused code
Version 0.2 (Jun 25, 2009)

Labels

Edit
plugin-external plugin-external Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Add Comment