Introduction

Using GitHub webhooks, you can make Jenkins build on every commit. This guide will show you how.

What are webhooks?

Webhooks are like APIs in reverse. With an API, you make requests to an API provider. Webhooks reverse this flow.

Instead of you making a request to the API provider, the Webhook provider makes a request to you. Your code receives the request, then does something with it. Examples of webhook requests would be Stripe sending you a notification you about a new payment or IFTTT sending you a notification of a new tweet from your Twitter account.

This diagram is a quick high level overview of how webhooks work

Ensure you have the Jenkins Github plugin installed

If you don't have it already, install the Jenkins Github plugin: https://plugins.jenkins.io/github/.

Configure a Jenkins branch to build on commit

Follow the documentation at https://plugins.jenkins.io/github/ to configure a branch to build on a github commit.

Start jenkins locally

Start jenkins locally, so you have it running on localhost.

Configure GitHub to send webhooks to Jenkins

To set up a Webhook, go to the settings page of your repository. From there, click Webhooks, then Add webhook.

You'll see a page like this:

Fill out all of the form as shown in the image, except for Payload URL.

Payload URL is where Github will send the payload to your server.

Jenkins is running on localhost so you if you are new to webhooks, you might think you can put localhost in there. However, this won't work. Thats because Github can't see your localhost.

Whenever anything requests localhost, it sends a request to itself. Thats why when you hit localhost in your browser you can access locally running servers like Jenkins. Therefore if you put localhost in there, Github will just send itself a request and it will never reach your Jenkins server.

You could deploy your new Jenkins setup to a remote server and get a public URL that way, but that would take a lot of time to set up and configure.

Instead, we can use a simple tool I've built called expose to give your computer a public URL.

Install expose

For Mac or Linux, go to Expose.sh and copy/paste the installation code shown into a terminal.

For Windows go to Expose.sh, download the binary and put it somewhere in your PATH.

Expose Jenkins to the web

Run expose <port> where port is the port your API server is running on, like 80 or 8080.

If you have Jenkins running on port 80, this would be expose 80.

Expose.sh will generate a random public expose.sh URL. You'll see output like this:

expose 80
http://m2hh3u.expose.sh is forwarding to localhost:80
https://m2hh3u.expose.sh is forwarding to localhost:80

Take the generated URL and put it into the Payload URL field, then click the "Add Webhook" button down at the bottom of the form.

Make a commit to your master branch

Make a commit to the master branch of your Github repo. This should trigger the commit webhook back to Jenkins and your branch should start building. Now you have a working integration.

Custom subdomains

Using a custom subdomain (like myapi.expose.sh) would save you from needing to reconfigure a different URL each time in Github.

Expose.sh is free to use for randomly generated subdomains. If you want to use your own custom subdomains like myapi.expose.sh, you can do this for as little as $4.99/month depending on how many domains you want to use.

Its usually a good time vs money investment, considering the hourly rate of most people who use expose.sh for work.

Here's an example using a custom subdomain, you can Sign up here.

expose 80 as mysite.expose.sh
https://mysite.expose.sh is forwarding to localhost:80
http://mysite.expose.sh is forwarding to localhost:80

Conclusion

As you can see, using expose.sh to validate a webhook integration is much faster than doing it using a remote server. Expose.sh is free to use for random subdomains. You can use custom domains for as little as $4.99 per month.

Happy coding!