How to update Jenkins build status in GitHub pull requests [Step-by-Step Tutorial]

This is especially frustrating since other continuous integration servers, like Travis and Circle CI, make this easy.

Since Jenkins is the third most popular continuous integration tool used with GitHub (after Travis and Circle CI), you’d think this issue would have been solved.

But when I started looking online for a way to solve this issue. I found some good resources, but not one document that described the process from beginning to end with all the configurations needed.

So, to spare you the pain I’ve gone through trying to make this work, I wrote this end-to-end tutorial on how to update Jenkins build status in the GitHub pull request page.

So let’s dive in!

The Big Picture

To get a better understanding of the interaction between those tools and the problem they present, see the following diagram. The red marks are the parts that are missing and this post is attempting to fix.

Get the basics in place

To follow the steps below, you just need a couple of things:

1. A GitHub account.
2. A Jenkins server up and running on a static URL.

What you will do in this tutorial:

1. Setup GitHub
   1. Install Jenkins plugin
   2. Generate a GitHub access token
2. Setup Jenkins
   1. Install Hudson Post Build Task plugin
   2. Call the GitHub API

   3) Bask in the awesomeness of your technical prowess

Setup GitHub

So, how to get GitHub setup with Jenkins? These steps explain.

What you’ll do here is install the Jenkins plugin on your GitHub repository in order to trigger a build in Jenkins when you commit a change in GitHub. This way, Jenkins can run tests to make sure your code is working as expected.

On your GitHub account, go to your repository and configure a webhook to the Jenkins server:

1. In your browser, go to your GitHub account. The URL should be something like www.github.com/your_username
2. Go into one of your repositories
3. Click on Settings, on the upper right part of the page
4. Click on Webhooks
5. Click on Add Webhook
6. Set the payload url to <http://your_jenkins_server_url>/github-webhook/
7. Set Content type to application/json
8. Select the event you would like the webhook to be triggered by (I set my webhook to be triggered by “Just the push event”.
9. Click on Add webhook

Here’s what those steps look like visually:

So, how to get GitHub setup with Jenkins? These steps explain.

What you’ll do here is install the Jenkins plugin on your GitHub repository in order to trigger a build in Jenkins when you commit a change in GitHub. This way, Jenkins can run tests to make sure your code is working as expected.

On your GitHub account, go to your repository and install the Jenkins plugin:

1. In your browser, go to your GitHub account. The URL should be something like www.github.com/your_username
2. Go into one of your repositories
3. Click on Settings, on the upper right part of the page
4. Click on Integrations and services
5. Click on Add service
6. Search for Jenkins
7. Add your Jenkins static URL or IP.
8. Click on Add service

Here’s what those steps look like visually. 

 

Generate a GitHub access token

You will need to generate a GitHub access token for security purposes. This token can be used by an application to use an API, here the application is Jenkins and the API is the GitHub API to update the Jenkins build status in the pull request.

 Ok, now you’re on to some non-obvious items.

1. Go to your GitHub account.
2. Under your profile, open the drop-down menu and click on Settings.

3. Go to Developer settings on the left side menu, all the way on the bottom:

4. Click on Personal access tokens:

5. On the top right corner of the screen click on the Generate new token button.

6. Insert your password.

7. Under repo check the repo:status checkbox.

9. Click on Generate token at the bottom of the page.

10. Make sure to save your token somewhere so you can use it later, such as in the curl commands above.

Jenkins setup

So, how to get Jenkins working with GitHub? Let’s show you how.

What you’ll do here is set up your Jenkins project to run your automation tests and call the GitHub API to update the status of the commit with success or failure.

Install GitHub plugin:

1. In your browser, go to your Jenkins URL
2. Click on Manage Jenkins
3. Click on Manage Plugins
4. Go to Available tab and search for GitHub integration plugin
5. Check the checkbox on the left and click on download and install after restart

Setup GitHub configuration:

1. Go to your GitHub project
2. Click on Configure
3. On the top bar, click on Source code management
4. Check the Git  checkbox
5. Paste the repository URL that you would like to integrate with under repository URL.
6. Set the Branch to integrate with under Branch specified.

Now that you have GitHub setup, do the following:

1. In your browser, go to your Jenkins URL
2. Click on Manage Jenkins
3. Click on Manage Plugins
4. Click on Install Hudson Post Build Task

Here’s what you’ll see when you run each of those commands. First, the Manage Jenkins command, in the menu bar on the left side:

Next, the Manage Plugins command.

And finally, the Install Hudson build task command.

(In case you’re wondering why you’re installing a Hudson plugin and not a Jenkins plugin, it’s because of this interesting bit of CI historical trivia.)

Install Hudson Post Build Task plugin

The next step is to go into your Jenkins project post build actions, and add two post build tasks. One task for success, and another for failure. You will need those actions to distinguish between a successful build and a build that failed.

• The plugin name could also be called “post build task”

Define those build actions as follows:

What you are doing is looking for the words “SUCCESS” or “FAILURE” in the Jenkins log. When you find “SUCCESS”, you run a script that uses the curl command to call the GitHub webhook API to set the build status of the commit that started the build in GitHub pull request. The commit identifier, the SHA, is accepted by Jenkins within an environment variable – $GIT_COMMIT. Similarly, if you find “FAILURE” in the Jenkins log, you use curl to let GitHub know that the Jenkins build failed.

Either way, the status will be updated in the pull request. And, if you run Applitools tests, the Applitools status will also be updated.

Call the GitHub API

For log entries containing “SUCCESS”, here’s the post-build command that you want Jenkins to run:

And for log entries containing “FAILURE”, here’s the post-build command that you want Jenkins to run::

Notice that you will need to replace the following with your relevant info:

• <GitHubUserName> – from GitHub
• <REPO_NAME> – from GitHub
• <YOUR_GITHUB_TOKEN>
• <YOUR_JENKINS_URL>
• <JenkinsProjectName> – your Jenkins project name

Let’s dig into these post-build commands, using the curl man pages.

As you can see, these are having curl request a URL from api.github.com. This URL has your GitHub username, repository name, and access token in it.

You’re sending a JSON snippet in the header of the HTTP request, as specified by the -H option. And you’re sending an HTTP POST request, as indicated by the -X flag. And the data that post command is sending, indicated by -d, is a bit of JSON with either success or failure, your Jenkins URL, and your Jenkins project name.

(That’s some pretty complex curl you got going!)

Once you get it setup be sure to give yourself a pat on the back. Or a nice Belgian waffle with whipped cream and strawberries. (I know which one I’d pick!)

So, where do you get all this information?

To get this info, you’ll do the following:

• GitHub Username – This should be your GitHub username. Hopefully this is obvious.
• GitHub Repository Name – You can find the name of any particular GitHub repo at the top of its page. In the example below, the repo name is Applitools-GitHubIntegration.

• Jenkins URL – This should be the base URL of your Jenkins server. This is simply the URL you put into your browser to access Jenkins, without anything to the right of the domain name. For example, if you have a Jenkins server setup on Amazon EC2, it might look something like this:

http://ec2-53-70-132-187.compute-1.amazonaws.com/

In order for GitHub to find your Jenkins server, you should plug in your fully qualified domain name.

• Jenkins Project Name – which you can see in the Jenkins UI as shown below.

Conclusion

Now that you’ve configured both Jenkins and GitHub, the commit status will be shown in the GitHub pull request page when you merge a PR:

As you can see, the Jenkins build status is now appearing in the pull request page. 

Pretty nice, right?