Monolune

How to display Jenkins build statuses on GitHub

Setting up Jenkins and GitHub to work together can be a challenge. The steps to make GitHub display Jenkins build statuses are not obvious at all. This guide will demonstrate setting up a new Jenkins project with GitHub integration, but most of the steps will still be applicable if you are looking to integrate GitHub with existing Jenkins projects. I will point out the differences as they appear. I wrote this both as guide for those looking to display build statuses, and for me, because the steps are so non-obvious that I actually forget them every time.

Steps

1. Generate a GitHub personal access token

GitHub personal access tokens are substitutes for the usual GitHub user password. They are effectively the same as your GitHub password, except that you can define permissions for them. These tokens will be useful for Jenkins tasks that have to 'log in' to your GitHub account (to set build statuses, for example).

  • On GitHub, go to Settings > Personal access tokens (you can access settings by clicking on your user icon on the top right. A drop-down should appear, with Settings as one of links).
  • Generate a new personal access token.
  • The only permissions you need is to give full control of private repositories. This applies even if you do not have private repositories.

2. Install the GitHub plugin for Jenkins

This well-supported Jenkins plugin is commonly used to interact with GitHub.

  • In Jenkins, go to Jenkins > Manage Jenkins > Manage Plugins to install the GitHub plugin.

3. Define a GitHub server on Jenkins

  • In Jenkins, go to Jenkins > Manage Jenkins > Configure System.
  • Under GitHub, add a GitHub server. Provide your login credentials. Set the username to your GitHub username, and set the password to a GitHub personal access token with full permissions over private repositories (see step 1).
  • Under GitHub > Advanced, check the Override Hook URL checkbox and take note of the default hook URL (i.e. the URL where Jenkins expects GitHub to send messages to notify Jenkins of events that happen to specific GitHub repositories). Be sure to uncheck the checkbox.

4. Add a new Jenkins project (or modify an existing one

If you already have an existing Jenkins project to try these steps on, go to your Jenkins project's page and click on Configure project and skip the first two bullet points below. Otherwise, you may follow along.

  • In Jenkins, go to Jenkins > New Item.
  • Select Freestyle project, and click OK.
  • Under Source Code Management, select Git. Provide the repository URL (e.g. https://github.com/example/my-repo.git). Make sure that the URL ends with .git. Provide your GitHub login credentials (i.e. GitHub username and personal access token).
  • Under Build Triggers, select GitHub hook trigger for GITSCM polling.
  • Under Post-build actions, select Set GitHub commit status (universal). Under the What: section, set Status result: to One of default messages and statuses.

5. Create a webhook for your GitHub repository

  • On GitHub, go to the repository for which you want to display build statuses for.
  • Go to Settings > Webhooks (do not confuse the repository Settings with the user Settings that we used to create personal access tokens).
  • Enter the URL webhook that you took note of in step 3 (e.g. https://test.example.com/github-webhook/). Note the trailing slash. Do not miss the trailing slash; it is important.
  • Select Just the push event as trigger for the webhook. You can test the webhook GitHub by sending test payloads.

What you should have at this point

At this point, a Jenkins build job should run whenever you push to your repository's master branch on GitHub. In addition, Jenkins will inform GitHub of the status of builds after they have completed. You should now see green ticks or red crosses beside branch names on GitHub after their Jenkins build jobs have completed. Congratulations! It is always fascinating to see automation at work.