Integrating Bitbucket and Jenkins

If you’re like me, you have your source code hosted in a hosted environment (such as Bitbucket), but you have a local continuous integration server (such as Jenkins). It would be really nice if you could have Jenkins build your project every time you commit, but without the heavy requirement of polling your repo. In this post, I’ll show you how to integrate the two to do just that.

The first step is to get Jenkins set up (the zeroth step, of course, is to have your code hosted by Bitbucket. I’ll leave that as an exercise for the reader ;). The basic job set up will vary, based on your project’s needs (Maven, Gradle, etc), so I’ll also leave that up to you. Once the project is setup, though, we need to configure remote access. This is done by selecting "Trigger builds remotely" under Build Triggers (and deselecting everything else). You will now be prompted to enter an Authentication Token. You can either create this yourself, or use, e.g., a password generator to do it for, which I would suggest, as it needs to be secure:

Once that is done, you might kick off a build to verify your Jenkins configuration.

Before we leave Jenkins, we need to get an API token for the user who will do the builds. This assumes, of course, that you have your instance secured, which I think is a reasonable assumption to make. To do that, from the Jenkins home page, click on People, click on the desired user, click configure on the left, then, finally, click on the API Token button.

Copy that value and save it somewhere.

With that done, we need to configure our Bitbucket repo now. Start by going to your project’s administrative area and clicking on hooks (https://bitbucket.org/{user}/{project}/admin/hooks). From the dropdown, select Jenkins, click Add Hook, then click on the edit link next to the newly created hook and fill in the form:

The endpoint, as shown in the image, will be {user}:{token}@{jenkins URL}. The module name must match exactly what you called it Jenkins, so I would suggest avoiding spaces in the name unless you don’t mind URL-encoding the module name. The token, of course, is the authentication token created above.

Click save, and you should now be ready to test the integration by pushing a change to the Bitbucket repo. Within just a few seconds, you should be able to see the build job running on your local Jenkins server. That assumes, of course, that that machine is addressable from outside your firewall. If it’s not, you’re probably stuck with either polling or building on a schedule. If your network supports it, though, this is a great way to get continuous builds when you need them without having to hammer the Bitbucket servers.