Setup GitHub and Jenkins integration for pull request builder and merger

In this example, we're going to run builds in Jenkins server based on events listed below. We'll set two Jenkins items/projects. First one Nation-PullRequest is to run builds for normal pull request events such as create, push, comment, close and reopen. The second one Nation-Merge is for just merging pull requests.

How it works

1. User creates a local branch.


2. User pushes local branch to GitHub.


3. User creates pull request for pushed local branch in GitHub.


4. GitHub tells Jenkins to run build.


5. Jenkins copies repository from GitHub to /var/lib/jenkins/workspace/Nation-PullRequest/ or /var/lib/jenkins/workspace/Nation-Merge/ directory.


6. Jenkins runs build tests.


7. Jenkins tells GitHub about the build result (success/failure). Applies only to Nation-PullRequest item.

Jenkins runs builds when:

• A pull request is first created by pushing a local branch.


• User pushes changes to an existing branch.


• User leaves Jenkins specific comments such as test this please, add to whitelist etc.


• User reopens closed pull request.


• User reverts merged pull request.


• Merging pull requests. Applies only to Nation-Merge item.

Overview

1. Create a GitHub repository.


2. Install Ubuntu server. 14.04


3. Install Apache server. 2.4.7


4. Install Git package. 1.9.1


5. Setup GitHub with SSH.


6. Install Jenkins server. 2.32.1


7. Jenkins GUI setup.


8. Install Jenkins GitHub plugins.


9. Configure Jenkins globally.


10. Configure GitHub web hooks.


11. Create a Jenkins project Nation-PullRequest.


12. Create a Jenkins project Nation-Merge.


13. Configure Jenkins project Nation-PullRequest.


14. Configure Jenkins project Nation-Merge.


15. Manually testing Jenkins projects.


16. Testing Jenkins GitHub pull request builder.


17. Testing Jenkins GitHub merge builder.

1. Create a GitHub repository

Our project is called nation and its properties are as follows.

Browser URL: https://github.com/Inanzzz/nation
Clone URL: https://github.com/Inanzzz/nation.git

2. Install Ubuntu server

I assume that you've already installed it and it is up an running.

3. Install Apache server

I assume that you've already installed it and http://localhost is working.

4. Install Git package

$ sudo apt-get update
$ sudo apt-get install git
$ git config --global user.name "Inanzzz"
$ git config --global user.email "inanzzz@helloworld.com"

$ git --version
git version 1.9.1

5. Setup GitHub with SSH

Full information can be found here.

6. Install Jenkins server

You need to have a JDK and JRE installed. At the time of writing this post openjdk-7-jre and openjdk-7-jdk were suggested.

Install JDK and JRE

$ sudo apt-get install openjdk-7-jre
$ sudo apt-get install openjdk-7-jdk

$ java -version
java version "1.7.0_121"
OpenJDK Runtime Environment (IcedTea 2.6.8) (7u121-2.6.8-1ubuntu0.14.04.1)
OpenJDK 64-Bit Server VM (build 24.121-b00, mixed mode)

Install Jenkins

$ wget -q -O - https://pkg.jenkins.io/debian/jenkins-ci.org.key | sudo apt-key add -
$ sudo sh -c 'echo deb http://pkg.jenkins.io/debian-stable binary/ > /etc/apt/sources.list.d/jenkins.list'
$ sudo apt-get update
$ sudo apt-get install jenkins

$ sudo service jenkins status
Jenkins Continuous Integration Server is running with the pid 11444

Log file: var/log/jenkins/jenkins.log

7. Jenkins GUI setup

Installation

• Go to http://localhost:8080.


• Unlock Jenkins by following the on screen instructions. Get password with $ sudo cat /var/lib/jenkins/secrets/initialAdminPassword.


• Select "Install Suggested Plugins" option to install default plugins.


• Ignore creating a new admin user and click "Continue as admin" button.


• Login with admin:ab56a379e3154a38acfc46b91bc0c25a credentials.


• Don't create a new admin so click "Continue as admin" button.

Configuration

• Change password to something you can remember by clicking "admin" tab on the right hand side of screen and "Configure" option in the menu.


• Manage Jenkins -> Configure Global Security


• Tick "Allow users to sign up" option under "Security Realm" of "Access Control" section.


• Select "Safe HTML" option under "Markup Formatter" section. Without this, the "Build History" section of your jobs won't render HTML links.

8. Install Jenkins GitHub plugins

• Go to http://localhost:8080.


• Manage Jenkins -> Manage Plugins


• If not installed by default, find and tick "Git plugin", "GitHub plugin", "GitHub Pull Request Builder" and "Rebuilder" plugins.


• Click "Install without restart" button.


• Restart Jenkins with $ sudo service jenkins restart.

9. Configure Jenkins globally

• Go to http://localhost:8080.


• Manage Jenkins -> Configure System


• Under "GitHub Pull Request Builder" section, do the following.


• OPTIONAL - If you have an alternative URL to access Jenkins from outside, you can add it to "Jenkins URL override" field. For testing purposes, I use ngrok to access it from outside so I'll have to add e.g. http://12345e55.ngrok.io/ into it. If I didn't:


1. GitHub and Jenkins wouldn't be able to talk to each other.


2. I would end-up seeing an unwanted entry in GitHub web hooks settings for Jenkins's IP address.


• Click "Add" button which is located next to select box associated with "Credentials" label.


• Select "Username with password" as "Kind" field.


• Type your GitHub login credentials in "Username" and "Password" fields then save.


• Add GitHub username Inanzzz into "Admin list" textbox.

10. Configure GitHub web hooks

Obtain web hook URL

• Go to http://localhost:8080.


• Manage Jenkins -> Configure System


• Under "GitHub" section, do the following.


• Click "Advanced" button.


• Tick "Specify another hook url for GitHub configuration" tickbox and obtain URL http://your-jenkins-domain.com:8080/github-webhook/ somewhere then untick it again.


• Exit without saving.

Enable web hook URL in GitHub

• Go to your GitHub repository.


• Click "Settings" tab.


• Click "Webhooks" menu option.


• Click "Add webhook" button.


• Type http://your-jenkins-domain.com/ghprbhook/ into "Payload URL" field. Pay attention to the difference with the original web hook URL we obtained above!!!


• Select x-www-form-urlencoded in "Content Type" field.


• Tick "Let me select individual events." option and tick just Issue comment, Pull request and Push options.


• Click "Add webhook" button.

If you see a green tick icon next to the webhook URL after refreshing the page means the link is working. If you click the link and scroll to the bottom of the page, you'll see GitHub and Jenkins communication details under "Recent Deliveries" section.

Enable Jenkins (GitHub) plugin service

• Go to your GitHub repository.


• Click "Settings" tab.


• Click "Integrations & services" menu option.


• Click "Add service" button and find Jenkins (GitHub plugin) service.


• Type http://your-jenkins-domain.com/github-webhook/ into "Payload URL" field. Pay attention to the difference with the original web hook URL we obtained above!!!


• Click "Add service" button.

11. Create a Jenkins project - Nation-PullRequest

• Go to http://localhost:8080.


• New Item


• Type "Nation-PullRequest" in "Enter an item name" field.


• Select "Freestyle project" option.


• Click "OK" to finish.

12. Create a Jenkins project - Nation-Merge

• Go to http://localhost:8080.


• New Item


• Type "Nation-Merge" in "Enter an item name" field.


• Select "Freestyle project" option.


• Click "OK" to finish.

13. Configure Jenkins project - Nation-PullRequest

• Go to http://localhost:8080.


• Click "Nation-PullRequest" item from the list.


• Click "Configure" option.


• General


• Tick "Discard old builds" option.


• Type 20 in "Max # of builds to keep" field.


• Tick "GitHub project" option.


• Type https://github.com/Inanzzz/nation in "Project URL" field.


• Tick "This project is parameterized" option. This will change default "Build Now" option with "Build with Parameters" in project's menu. By default it will run the last build or if you pass a commit hash value from the "Build History" list or GitHub pull request, it will run a specific build which is a good thing.


• Click "Add Parameter" button.


• Select "String Parameter" option.


• Type sha1 in "Name" field.


• Source Code Management


• Tick "Git" option.


• Type https://github.com/Inanzzz/nation.git in "Repository URL" field.


• In the "Credentials" select box, select the option you created under 9. Configure Jenkins globally bullet point earlier.


• Click "Advanced" button then type origin in "Name" and +refs/pull/*:refs/remotes/origin/pr/* in "Refspec" field.


• Type ${sha1} in "Branch Specifier" field.


• Build Triggers


• Tick "GitHub Pull Request Builder" option. You'll see that your previous configs will appear there.


• Tick "Use github hooks for build triggering" option.

14. Configure Jenkins project - Nation-Merge

• Go to http://localhost:8080.


• Click "Nation-Merge" item from the list.


• Click "Configure" option.


• General


• Tick "Discard old builds" option.


• Type 20 in "Max # of builds to keep" field.


• Source Code Management


• Tick "Git" option.


• Type https://github.com/Inanzzz/nation.git in "Repository URL" field.


• In the "Credentials" select box, select the option you created under 9. Configure Jenkins globally bullet point earlier.


• Type origin/develop in "Branch Specifier" field. In the case of hotfix and release, it will help to run tests.


• Type origin/master in "Branch Specifier" field. In the case of hotfix and release, it will help to run tests.


• Build Triggers


• Tick "GitHub hook trigger for GITScm polling" option.

15. Manually testing Jenkins project

Nation-PullRequest

• Go to http://localhost:8080.


• Click "Nation-PullRequest" item from the list.


• Do one of the following:


• Click "Rebuild Last" option and hit "Build". Don't change the value in "sha1" field.


• Click "Build with Parameters" option and hit "Build". Leave "sha1" field empty.

Jenkins log will appear as below.

$ tail -f /var/log/jenkins/jenkins.log

Jan 14, 2017 8:02:59 PM org.jenkinsci.plugins.ghprb.GhprbTrigger stop
INFO: Stopping the ghprb trigger for project Nation-PullRequest
Jan 14, 2017 8:02:59 PM org.jenkinsci.plugins.ghprb.GhprbTrigger start
INFO: Starting the ghprb trigger for the Nation-PullRequest job; newInstance is true
Jan 14, 2017 8:03:06 PM hudson.model.Run execute
INFO: Nation-PullRequest #1 main build action completed: SUCCESS

If you open "Console Output" of build #1 shown below, you'll see useful information about build.

Nation-Merge

There has to be a build in "Build History" list to carry out this test.

• Go to http://localhost:8080.


• Click "Nation-Merge" item from the list.


• Do one of the following:


• Click "Rebuild Last" option.


• Click "Build Now" option.

Jenkins log will appear as below.

$ tail -f /var/log/jenkins/jenkins.log

Jan 14, 2017 8:02:59 PM org.jenkinsci.plugins.ghprb.GhprbTrigger stop
INFO: Stopping the ghprb trigger for project Nation-Merge
Jan 14, 2017 8:02:59 PM org.jenkinsci.plugins.ghprb.GhprbTrigger start
INFO: Starting the ghprb trigger for the Nation-Merge job; newInstance is true
Jan 14, 2017 8:03:06 PM hudson.model.Run execute
INFO: Nation-Merge #1 main build action completed: SUCCESS

If you open "Console Output" of build #1 shown below, you'll see useful information about build.

16. Testing Jenkins GitHub pull request builder

Creating a pull request

We create a new branch feature/update-gitignore in our local PC, commit to it and push it to remote GitHub repository. Jenkins starts building after we create the pull request in GitHub, not before. It waits for us!

Jenkins log will appear as below after pushing the the new branch feature/update-gitignore.

$ tail -f /var/log/jenkins/jenkins.log

Jan 14, 2017 8:20:38 PM org.jenkinsci.plugins.ghprb.GhprbRootAction handleAction
WARNING: Request not known for event: push
Jan 14, 2017 8:20:38 PM org.jenkinsci.plugins.github.webhook.subscriber.DefaultPushGHEventSubscriber onEvent
INFO: Received PushEvent for https://github.com/Inanzzz/nation

Jenkins log will appear as below after starting and finishing build for feature/update-gitignore.

$ tail -f /var/log/jenkins/jenkins.log

Jan 14, 2017 8:21:35 PM org.jenkinsci.plugins.ghprb.GhprbRootAction handleAction
INFO: Checking PR #3 for Inanzzz/nation
Jan 14, 2017 8:21:35 PM org.jenkinsci.plugins.ghprb.GhprbTrigger handlePR
INFO: Checking PR #3 for job Nation
Jan 14, 2017 8:21:35 PM org.jenkinsci.plugins.ghprb.GhprbPullRequest 
INFO: Created Pull Request #3 on Inanzzz/nation by Inanzzz () updated at: 1/14/17 8:35 PM SHA: 8f81f2b57df92b7ba0886e9f4ba3c8431b352581
Jan 14, 2017 8:21:35 PM org.jenkinsci.plugins.ghprb.GhprbPullRequest updatePR
INFO: Pull request #3 was updated on repo Inanzzz/nation but there aren't any new comments nor commits; that may mean that commit status was updated.
Jan 14, 2017 8:21:51 PM hudson.model.Run execute
INFO: Nation #3 main build action completed: SUCCESS

If you go to Jenkins GUI, you'll see more details about the builds.

Test this please comment command

You can leave test this please comment to your PR to manually trigger Jenkins build which will be based on last commit. There are more "comment commands" which can be found in Jenkins system configuration settings under "GitHub Pull Request Builder" section or here.

$ tail -f /var/log/jenkins/jenkins.log

Jan 14, 2017 8:42:16 PM org.jenkinsci.plugins.ghprb.GhprbRootAction handleAction
INFO: Checking issue comment 'test this please' for repo Inanzzz/nation
Jan 14, 2017 8:42:16 PM org.jenkinsci.plugins.ghprb.GhprbTrigger handleComment
INFO: Checking comment on PR #3 for job Nation
Jan 14, 2017 8:42:17 PM org.jenkinsci.plugins.ghprb.GhprbPullRequest updatePR
INFO: Pull request #3 was updated/initialized on Inanzzz/nation at 1/14/17 8:55 PM by Inanzzz (comment)
Jan 14, 2017 8:42:27 PM hudson.model.Run execute
INFO: Nation #4 main build action completed: SUCCESS

17. Testing Jenkins GitHub merge builder

We already have a PR in GitHub for branch feature/update-gitignore so we just need to hit "Merge pull request" button.

Jenkins log will appear as below after hitting "Merge pull request" button.

$ tail -f /var/log/jenkins/jenkins.log

INFO: Received PushEvent for https://github.com/Inanzzz/nation
Jan 14, 2017 2:24:22 PM org.jenkinsci.plugins.github.webhook.subscriber.DefaultPushGHEventSubscriber$1 run
INFO: Poked Nation-Merge

Jenkins log will appear as below after hitting "Confirm merge" button.

$ tail -f /var/log/jenkins/jenkins.log

Jan 14, 2017 2:24:24 PM com.cloudbees.jenkins.GitHubPushTrigger$1 run
INFO: SCM changes detected in Nation-Merge. Triggering #9
Jan 14, 2017 2:24:35 PM hudson.model.Run execute
INFO: Nation-Merge#9 main build action completed: SUCCESS

If you go to Jenkins GUI, you'll see more details about the builds.

Readings

• GitHub pull request builder plugin


• Connecting to GitHub with SSH