How to add a Github webhook to Jenkins
Tags: github, webdev, jenkins, devops
Published: 2020-12-26 09:36:01

## 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
<img src="https://expose.sh/blog/jenkins-add-github-webhook/what-are-webhooks.png" style="width:800px"></img>

## 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/](https://plugins.jenkins.io/github/).

## Configure a Jenkins branch to build on commit
Follow the documentation at [https://plugins.jenkins.io/github/](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:
![Github webhook settings](https://expose.sh/blog/jenkins-add-github-webhook/github-webhook-add.png)

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](https://expose.sh?utm_source=dev.to&utm_campaign=jenkinsGithubWebhook) and copy/paste the installation code shown into a terminal.

For Windows go to [Expose.sh](https://expose.sh?utm_source=dev.to&utm_campaign=jenkinsGithubWebhook), 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](https://dashboard.expose.sh?utm_source=dev.to&utm_campaign=jenkinsGithubWebhook).
```
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!