Wednesday, January 11, 2012

Better Integration Between Jenkins and GitHub (with the GitHub Jenkins Plugin)


Overview

Jenkins (and in fact any CI systems) works best when builds are triggered after each and every commit. That provides you, the developer, with the most instant feedback possible. That, in turn, means you get fix(es) to the problems you introduced before you leave the context of what you were working on.

There are two general techniques for detecting commits in any source control system:
  • Polling (the "Dad, are we there yet... are we there yet... are we there yet!" technique) where you ask the source control system at regular intervals.
  • Push, where the source control system tells you there has been a change.
The first technique requires no support from the source control system but puts a lot more load on both the CI system and the source control system. As well as that, it can only pick up changes as often as the polling frequency.

The second technique requires support, in both the source control system and the CI system, for the sending and receiving of notifications.

The Jenkins GitHub plugin provides support for receiving push notifications from Github post-commit hooks and using those notifications to trigger jobs within Jenkins. It can set-up the post-commit hooks in GitHub for you.

In addition, GitHub decorates the Jenkins “Changes” pages with links to the pretty GitHub commit, issues pages and adds a sidebar link to the corresponding GitHub project page.

Stable Release Version

The current stable release is version 0.9

Requirement for Plug-in Use

There are not too many requirements for using this plugin:
  • Jenkins 1.400 or newer
  • Jenkins Git Plugin version 1.1.12 or newer
  • At least one GitHub hosted project to build ;-)

Step-by-Step Instructions on How to Use it

Installation

  1. Go to your Jenkins instances root page.
  2. If your Jenkins instance has security enabled, login as a user who has the Overall | Administer permission.
  3. Select the Manage Jenkins link on the left-hand side of the screen.
  4. Select the Manage Plugins link.
  5. On the Available tab, select the Github Plugin and click the Download and Install button at the bottom of the page (if you do not got the Git Plugin installed, do not worry, Jenkins is smart enough to install/upgrade the Git plugin, where required).
  6. Restart Jenkins once the plugins are downloaded (Note: users of Jenkins 1.442 or newer should be aware that the plugin currently requires a restart to function correctly).

Configuration

If all you want to do is enable the hyperlinks in the Recent Changes for the build, it is just a case of providing the GitHub project URL in the Jenkins job configuration, e.g.
  1. Goto your Jenkins instance job.
  2. Select the Configure link on the left hand side of the screen.
  3. In the GitHub project field, enter the URL of the GitHub project. If your GitHub project's git URL looks like: git@github.com:username/project.git,

    then the GitHub project should be:
    http://github.com/username/project/or if the project is private, you can get faster navigation with: https://github.com/username/project/
If you want to enable build triggering, you need to configure your Jenkins instance for receiving the push notifications from GitHub. There are two ways you can achieve this. The first way is to let Jenkins manage the Post-Receive URLs for you:
  1. Go to your Jenkins instances root page.
  2. If your Jenkins instance has security enabled, login as a user who has the Overall | Administer permission.
  3. Select the Manage Jenkins link on the left hand side of the screen.
  4. Select the Configure System link.
  5. In the GitHub Web Hook section select the Let Jenkins auto-manage hook URLs option.
  6. Ensure you have provided at least one username and password for connecting to GitHub (the password is required as GitHub does not expose an API for managing the Post-Receive URLs).
The second way is to manage the Post-Receive URLs yourself:
  1. Go to your Jenkins instances root page.
  2. If your Jenkins instance has security enabled, login as a user who has the Overall | Administer permission.
  3. Select the Manage Jenkins link on the left hand side of the screen.
  4. Select the Configure System link.
  5. In the GitHub Web Hook section select the Manually manage hook URLs option.
  6. For each project that you want to have triggering builds, you need to open the Repository Administration screen on that GitHub project's page.
  7. Select the Service Hooks tab.
  8. Select the Post-Receive URLs hook.
  9. Add the URL, which will be the root URL of your Jenkins instance with /github-webhook appended.
Once you have configured your Jenkins instance for receiving the push notifications, you can enable jobs being triggered via the push notifications:
  1. Goto your Jenkins instance job.
  2. Select the Configure link on the left hand side of the screen.
  3. Select the Build when a change is pushed to GitHub checkbox and save the configuration.

Tips & Tricks, How to Use it on DEV/RUN

The plugin is identical to configure on DEV@cloud.

Any Known Issues

  • The recent GitHub refresh of their site's look-and-feel broke automatic Post-Receive URL management for versions of this plugin prior to 0.9

Relevant Documentation

Cheers!

Stephen Connolly
Elite Developer & Architect


CloudBees
www.cloudbees.com
 
Follow CloudBees:
Facebook Twitter

6 comments:

  1. The GitHub Post-Receive hooks integration is not working now. Getting redirect to SSO site for login. =(

    Any update when it will be fixed or could you please advice any workaround for it?

    Thanks,
    Vladimir

    ReplyDelete
  2. Please make sure to use the trailing slash: /github-webhook/

    Note that you will get a 500 error unless you post the json document that the plugin expects.

    ReplyDelete
  3. Will the plugin operate the same with Github Enterprise?

    ReplyDelete
  4. I have tried the above advice and it did not work for me.

    I have posted my situation here.

    http://stackoverflow.com/questions/10633827/jenkins-github-plugin-work-with-private-repo-in-github-for-push-trigger

    Would love to get a definitive answer from cloudbees

    ReplyDelete
  5. Github Enterprise support BUMP.

    As asked by Bill almost 3 months ago, can this be configure with Github's Enterprise installation found here:
    https://enterprise.github.com/ ??

    I've searched all over and have not found anything that works.

    ReplyDelete
    Replies
    1. Yes, the same /github-webhook/ URI will work with github enterprise installations

      Delete