How to Point BitBucket Webhook to Jenkins on Localhost

If you want to host your Jenkins locally on your computer for testing, but are interested in leveraging BitBucket’s webhooks to point to your localhost, then you need to expose your computer to the outside world.  There are several ways to do this, but the easiest I have found is to use a tool called ngrok. If you do not have it installed already and are using a Mac, I would suggest that you install it with Homebrew. This post was inspired by some instructions found on  GitHub actually, as opposed to BitBucket.

[code language=”bash”]
$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
$ brew cask install ngrok
[/code]

You are ready to run ngrok now to expose your localhost to the outside world now. In this situation, I am demonstrating an example of exposing my local Tomcat; however, one word of caution is that you may not want to expose the default 8080 port. Reasons for doing this including a poor mans security to limiting the inbound traffic you expose yourself to by doing this. In order to change your default port for Tomcat, follow the instructions here. An even better option would be to expose a secure link on https.

So, presuming you have installed ngrok and you have changed your default port to something non-standard, then you are ready to run the tool to expose your machine to the outside world:

[code language=”bash”]
$ ngrok http 8282
[/code]

Once you run this command, you will see the program run in the foreground (ideally you would want to run this in the background and/or as a service on reboot). In order to test that you have set things up successfully, we can test by simply going to one of the two provided URLs in a browser and in my case it would take you to the Apache Tomcat landing page; however, we really want to test that we can get a webhook to work. So, in order to do this, we could use BitBucket to trigger a webhook to a Jenkins instance deployed to my local Tomcat whenever I push a code change to BitBucket. Here is the configuration:

Jenkins BitBucket webhook

Now, we just need to make a code change and push it for testing. We can see both from ngrok and BitBucket that things worked by witnessing the HTTP 200 OKs.

ngrok running and it has successfully received two push requests from the webhook in BitBucket

Jenkins BitBucket Webhook Successful 200 OK requests log

By default, ngrok will only give you a session that last few a few hours at a time. Your options are to periodically restart your tunnel to expose your IP to the outside world, which also means needing to update your webook with the newest URL, or to sign up and register an authorization token: https://ngrok.com/upgrade. Even so, if you restart your command again (ie, reboot your machine or accidentally close the terminal that you used to launched the program), then you will still get a new URL.. As you may have guessed, the want you to pay them to get a static address.