This post is about integrating GitHub and Jenkins so that each application can send messages to the other and update their status.
Use case: whenever a new pull request is created or an existing one is modified (i.e. new commit occurs) on GitHub in my repo, I want a Jenkins job to be triggered for that branch and that job should build the project for which the PR was created. After the job has ended, the result should be displayed on GitHub next to the commit which started the whole cycle.
Sounds like a dream, isn’t? Note that in the GitHub repository I had several projects under different folders, so when a new PR / branch is created, it is not obvious at first glance which project to build in Jenkins (using maven and modules).
After some investigation here is the guide how to set this up – probably there are some other solutions as well, but this one works like a charm.
You need to install the following plugins for Jenkins:
(I have tried out the Github Pull Request Builder plugin as well, but it has some security concerns plus it is up for adoption which is never a good news, so I didn’t want to use it.)
Used versions : Jenkins – 2.118, github plugin – 1.29, generic webhook trigger plugin – 1.32
- To connect Jenkins and GitHub you will need a token which can be generated in GitHub. Log in to GitHub (with the account which was already added as contributor to the repository and which will be used from Jenkins!) and under your user’s setttings you can find “Developer settings” menu. Under it there is the “Personal access token” option. Generate a token and save it for later use. Select admin:repo_hook and repo scopes.
- You need to set up a webhook on your GitHub repository as well. The webhook is for the Generic webhook trigger plugin and should be set for pull request events. The url can be found on the plugin’s wiki page. You can set up webhooks under your repo’s “Settings” menu, content type should be application/json.
- Next you need to create credentials under Jenkins using your GitHub token. Go to Jenkins / Credentials and probably under system / global credentials you can find the Add credentials link. Click on it and choose “Secret text” as Kind (thanks to Plain credentials plugin). The secret is the token, ID/Description can be set freely.
- Next you need to configure the GitHub plugin. Go to Manage Jenkins and find the GitHub section where you can add servers. Add one and select a fancy name for it. Note that credentials will be needed, select the one which has been created in the previous step. Remove the Manage hooks option as you have already set up the hooks. Test the connection, it should work at this point.
- Now you can create your job. Create a freestyle job. Find “GitHub project” option and set your repo’s URL. Then set up git as SCM. Then go to Generic Webhook Trigger as Build trigger and here you can create variables which will get their values from the json webhook messages coming from GitHub. Examples:
variable name: pr_number, expression: $.number, JSONPath
variable name: sender, expression: $.sender.login, JSONPath
v. name: branch, expression: $.pull_request.head.ref, JSONPath
You can get as much data as you want from the pull request json message. The structure of the general GitHub pull request message is here. About how to get out the data from a json file you can find information with google.
Whenever you set all the variables you want to use, you can create a shell script step to build anything and use these variables. Example: you can get the branch name, you can get the user who created / modified the pull request, you can get the title of the PR which can be used as indicator what to build, i.e. when the title contains a specific project code, you can checkout the branch and call “mvn clean install -pl projectname”. The main point is that for building something you need some information and these information can be found in the webhook message. Here comes the reason to use the Generic webhook trigger plugin : with this plugin you can check and use the content of the json message. With the general github plugin you can not.
You could ask at this point that why on earth did we set up the github plugin? The answer is that this plugin can send feedback to GitHub after the job has built the project. This is the last step in setting up the job correctly.
6. At the Post-Build Actions there is a step called “Set GitHub commit status (universal)”. Choose this and configure it: sha can be entered manually as variable coming from the json message ($.pull_request.head.sha) , set your repo and leave other values as default.
Save the job and we are ready!
Now you can test your configuration. Create a pull request (don’t forget to choose a proper title or name) in GitHub and check if the Jenkins job is triggered. Then commit something on the PR and check that – after the job was run – the commit gets the build result in GitHub (select your PR and the commits tab).
I hope this guide helps you to integrate Jenkins and GitHub a bit easier. Enjoy and long live the DevOps!