Trigger a Jenkins job on code push event in Github via webhooks

Overview

In this post, we will discuss a fairly common use case where the source code is stored in version control like Github. We will create a job in Jenkins and integrate it with GitHub. Whenever code is updated in the GitHub repository, an event gets triggered via webhook which invokes a Jenkins job that has been integrated with this GitHub repo (repository) .

We will walk through the implementation of this use case with Github webhooks and Jenkins. We will discuss how a Jenkins job gets triggered on code push event via Github webhooks for freestyle, pipeline and multi branch pipeline projects.

Setup Github Webhook

First let us setup the webhook in Github repo. Webhook setup is a common step for all the three type of Jenkins projects mentioned in subsequent sections.

To setup the webhook, you need to goto your Github repo – > Settings (from top navigation bar) -> Webhooks (from left side navigation bar) -> Add webhook -> <jenkins url>/github-webhook.

Under Which events would you like to trigger this webhook?, we have selected “Send me everything”. With this selection, we are automatically opted-in for future updates utilizing webhooks. You can also select “Just the push event” if you want to setup webhook just for the push event.

Please do not mention localhost url. Github will not be able to recognize it. If you are using localhost, consider a utility like ngrok to expose your local machine server to the Internet with minimal effort.

The next step is to setup the Jenkins project to poll the Github repo for any change.

Freestyle projects

For freestyle  projects, a separate tab called “Source Code management” (SCM) is available. Url for Github repo and credentials need to be provided in this section. 

Now goto Build Triggers section and check the option “GitHub hook trigger for GITScm polling”.  If this option is selected, this job will get triggered when Jenkins will receive PUSH GitHub hook from repo defined in Git SCM section. 

Pipeline project

In a similar manner, you can setup the pipeline project to trigger the build on receiving push event from Github. 

Even for this job type, check the option “GitHub hook trigger for GITScm polling” in the “Build Triggers” section. 
After selecting this option, all you need to do is run the build first time from within Jenkins using “Build Now” option. This will enable jenkins to register the github event, so that from then onwards whenever you push the code in github it will automatically run this job in jenkins.

Within the pipeline, you should have a code checkout step. This can be in your pipeline script in jenkins or jenkinsfile in the same github repo where you have added the webhook.

Apart from the Jenkins GUI as discussed above, there is another way to setup the property,  “GitHub hook trigger for GITScm polling”. In the jenkinsfile at the top of the file or within the relevant stage, add the property as follows:  properties([pipelineTriggers([githubPush()])])

The above code was generated by selecting the hyperlink Pipeline Syntax just below groovy script text area. Then select Snippet Generator from left hand side navigation bar. From the Sample Step drop select  properties: Set job properties. Then check the checkbox for the property: “Github hook trigger for GITScm polling” and click on Generate Pipeline Script. The script generated is same as the one mentioned above, which you can insert within your script. When you run the build for the first time after setting up the project, it will enable this property within jenkins job.

Multibranch Pipeline project

Similarly, we can setup a multi branch project. For this project type, goto Branch sources section and select GitHub from “Add Source” drop down and provide the details for the repository.

Then in the Build Configuration section, select the appropriate jenkinsfile path. The job will build the first time as soon as you save it and any Github push event in the selected branch will now trigger it.

Let us know if you found the post helpful.