This post details the setup necessary to get Jenkins work with Bitbucket webhooks and the steps involved:

 

Install Jenkins

Install Jenkins LTS, that is what I have used, on FreeBSD it is pkg repositories, on Debian/Ubuntu you need to configure the repository once, please follow below instructions:

https://pkg.jenkins.io/debian-stable/

 

Jenkins requirements to have it ready to work with Bitbucket webhooks:

  • Jenkins reachable from public Bitbucket APIs/IPs address.
  • Jenkins having a user account enabled with API token to accept incoming triggers.
  • SSH key of jenkins node having read only access to Bitbucket repos.
  • Jenkins instance having appropriate roles attached to make use of AWS services/resources, if necessary, otherwise not required.

Configure Jenkins

  • Create a user with API token to authenticate, save the token, it will be used later.

user-api-token-creation

 

  • Add/Modify the user privileges to read/build and workspace read permissions in the matrix:

 

user-privileges-matirx

 

 

Create and configure Jenkins Job/Pipeline

  • Create either a freestyle or a pipeline job and modify Build triggers like below screen:

job-build-triggers

 

Read the note below the text field and you get two types of URLs to use:

One without any parameters, like JENKINS_URL/job/my-job/build?token=TOKEN_NAME

Another with ‘buildWithParameters’ which allows the request call to pass in parameters to be used, like JENKINS_URL/job/my-job/buildWithParameters?token=TOKEN_NAME&paramone=FIRST&paramtwo=SECOND

 

This helps you to trigger a jenkins job/pipeline by a webhook and pass parameters required for the task, like say in a parameterized job/build.

 

Make Jenkins reachable from public network:

With Jenkins jobs created and configured, it must be reachable from public or the many endpoints/IPs of BitBucket. In my case I am not using any reverse proxy, so my installation is on TCP:8080.

NOTE:  Take special care, like using strong passwords on Jenkins user accounts, patching jenkins to latest stable release and limiting privileges of the account created for automation. This is necessary as jenkins will be exposed to the Internet. Otherwise your Jenkins setup is at risk, as at some point the Jenkins installation may get compromised due to weak passwords or vulnerabilities!

Configure Bitbucket webhooks:

 

With the Jenkins setup complete we can now configure Bitbucket to send requests on certain events. Bitbucket configuration is easy compared to Jenkins as the settings are pretty intuitive.

Go to the settings of the repository, click on ‘Webhooks’, this will list the available webhooks, you need to add a new one and select the required triggers.

add-a-new-webhook

 

Now the Jenkins URL needs some addition, recall that there was 35 character API token that we generated while creating a user account in jenkins for automation, add this token in the URL before the FQDN/IP address, like:

JENKINS_URL/job/my-job/build?token=TOKEN_NAME

Will become:

http://JENKINS_USER_NAME:35_char_API_TOKEN@Jenkins_FQDN_IP:8080/job/my-job/build?token=TOKEN_NAME

Paste the URL of this sort, select the appropriate triggers and save the webhook settings.

You can now test whether the webhook triggers