In this tutorial, we will show a Jenkins Bitbucket integration using webhooks. It will work behind a firewall, inside a private network. You can use this setup for other services too - such as GitHub, GitLab or anything else that emits webhooks.

Main advantages of Webhook Relay here are:

• No delay between polling requests
• Additional security layer as Jenkins is not exposed to the internet as webhooks by default are uni-directional, responses are not returned to the caller.

Prerequisites

• Webhook Relay account, create one here.
• Jenkins instance. We will not go into installing Jenkins itself as there are quite a few options and many articles on that. See Jenkins official docs for up-to-date instructions.
• Bitbucket account and a repository that you will want to use.

Configure webhook forwarding

We will be using the Jenkins Bitbucket plugin . This plugin exposes a single endpoint to which we can send webhooks from multiple Bitbucket repositories.

Go to the internal URL forwarding setup page https://my.webhookrelay.com/new-internal-destination and enter your Jenkins address. In my case I will be running the agent on the same machine as Jenkins so the address for me is http://localhost:8080/bitbucket-hook/:

Follow the instructions to setup the agent and being forwarding webhooks. You will get your public URL that you can use in Bitbucket webhook configuration.

As you can see in the screenshot above, take the "Listening on" address.

Configure Bitbucket

For Bitbucket webhook configuration you can follow the plugin guide here: https://plugins.jenkins.io/bitbucket/#plugin-content-bitbucket-cloud-usage. You need to go to the repository settings and then to the webhooks section add "Add webhook" with the public URL that you have gotten from the previous step:

Bitbucket will be sending webhooks to Webhook Relay and our service will forwarding them to your internal Jenkins instance.

Configure Jenkins

Ensure you have the Bitbucket Jenkins plugin. Plugin instructions can be found here: https://plugins.jenkins.io/bitbucket/#plugin-content-bitbucket-cloud-usage.

In your repository configure the build trigger:

Testing

Once the agent is running, you can test by pushing a commit to your repository. You should see a build being triggered in Jenkins:

You should also see it in the terminal where you started Webhook Relay agent:

relay forward -b localhost-9Jk06s
Filtering on bucket: localhost-9Jk06s
Starting webhook relay agent...
2023-09-24 23:03:10.884 INFO    using standard transport...
2023-09-24 23:03:10.951 INFO    webhook relay ready...  {"host": "my.webhookrelay.com:8080", "buckets": ["localhost-9Jk06s"]}

Troubleshooting

There are several places to look for logs:

• Webhook Relay bucket details. It will show all your webhooks and their requests, responses.
• Jenkins system logs. You can find them in the Jenkins UI under "Manage Jenkins" -> "System Log".

Response "200" in Webhook Relay logs but no build

It's possible that you don't have the SCM configuration matching your Bitbucket repository. Check the system logs in Jenkins for errors such as:

PM WARNING com.cloudbees.jenkins.plugins.BitbucketJobProbe triggerMatchingJobs
No SCM configuration was found!

If you find them, add your repository to the SCM configuration in the Jenkins job.

On Webhook Relay all logs appear as "received"

You need to start the agent, follow the instructions here https://webhookrelay.com/v1/installation/. Agent is required to run in order to receive and forward webhooks.

Bitbucket server

Bitbucket server webhook to jenkins example can be found here https://plugins.jenkins.io/bitbucket/#plugin-content-bitbucket-server-usage. You mostly need to install a webhook plugin https://marketplace.atlassian.com/apps/1215474/post-webhooks-for-bitbucket?hosting=server&tab=overview and then create a Post-WebHook, which is different from WebHook and enable on push.

Originally published on https://webhookrelay.com/v1/tutorials/bitbucket/