Issue
-
I want to configure Jenkins and Bitbucket Server to automatically trigger Multibranch or Bitbucket Team/Project jobs on changes
Environment
-
CloudBees Jenkins Enterprise - Managed controller (CJE-MM)
-
Bitbucket Server
-
Post Webhooks for Bitbucket
-
Bitbucket Server Native Webhook API
Resolution
The Bitbucket Branch Source plugin provides support for integration of Bitbucket with multibranch project such as Pipeline Multibranch. The API listens for notification to the endpoint /bitbucket-scmsource-hook/notify.
Configuration in Jenkins
Global Configuration
(This is not applicable to versions older than Bitbucket Branch Source 2.2.0)
Configure a Bitbucket Endpoint under :
Multibranch Project
To track a single repository, create an item of type Multibranch Pipeline and use the Bitbucket branch source:
Configure the SCM Source (refer to the help tooltips of each Behavior to better understand what it does):
Older Versions
Prior to Bitbucket Branch Source 2.2.0, there is nothing to configure in . Configure the SCM as explained in the documentation of the Bitbucket Branch Source Plugin. In the Advanced section, specify the Bitbucket server URL - as well as the SSH port if using SSH authentication for checkout credentials:
Bitbucket Team/Project
To track multiple repositories of a Bitbucket project, create an item of type Bitbucket Team/Project and use Bitbucket Team/Project repository source:
Configure the SCM Source (refer to the help tooltips of each Behavior to better understand what it does):
Older Versions
Prior to Bitbucket Branch Source 2.2.0, there is nothing to configure in . Configure the SCM as explained in the documentation of the Bitbucket Branch Source Plugin. In the Advanced section, specify the Bitbucket server URL - as well as the SSH port if using SSH authentication for checkout credentials:
Further Configuration: Hook Management
Once a project is saved, it automatically listens for events - commonly sent by webhooks - on the endpoint /bitbucket-scmsource-hook/notify.
The option Manage Hooks may be enabled for a specific endpoint under to allow Jenkins to automatically register webhooks to that endpoint. This is the recommended, quicker, easiest configuration.
Notice that there are two different implementations to use for managing webhooks
-
Native: It will automatically create the webhook in the Webhooks section, which is the implementation of the native Bitbucket Webhooks -
Plugin: It will automatically create the webhook in the Post Webhooks section, which is the implementation of the Bitbucket WebPost Hooks Plugin.
Both options could be used, but the Native option is the recommended one in case you are running Bitbucket Server >= 5.4.0, version in which the native webhook integration was added. Since this version it is not really needed to use the Bitbucket WebPost Hooks Plugin - but you can still use it if you would like.
Since version 2.3.0, the Bitbucket Server Native Webhook API is supported. The global configuration provides an option to choose whether to use the native API - option native - or the Post Webhooks for Bitbucket add-on - option plugin.
|
Older Versions
Between Bitbucket Branch Source 2.1.1 and Bitbucket Branch Source 2.2.0 and since Post Webhooks for Bitbucket 1.4.1 (bitbucket add-on), the option Auto-register webhook may be enabled to let Jenkins automatically register a webhook for scanned repository/ies. This is the recommended, quicker, easiest configuration.
Even Older Versions
Prior to Bitbucket Branch Source 2.1.1, the only workaround is to configure each repository hook manually in Bitbucket Server. However the Bitbucket REST API can be used to facilitate that process, have a look at the article Generate webhooks in Bitbucket Server via REST API for Pipeline Multibranch.
Configuration in Bitbucket Server
If Jenkins is not setup to automatically manage webhooks, see below to understand how to manually create the webhooks for a repository:
Bitbucket Branch Source 2.3.0+ / Bitbucket Server 5.4+
Bitbucket Server 5.4 introduced a native Webhook API. Support for this API has been implemented in Bitbucket Branch Source version 2.3.0.
To create a webhook, go to the Settings of a repository, section Webhooks and click on "Create webhook":
Give it any "title" and specify the Bitbucket Branch Source endpoint $JENKINS_URL/bitbucket-scmsource-hook/notify?server_url=<BITBUCKET_URL>. Use the Test Connection feature to ensure that the webhook is able to ping the Jenkins URL:
Note In case you are using the Bitbucket WebPost Hooks Plugin, then the Branch Source endpoint should be just $JENKINS_URL/bitbucket-scmsource-hook/notify as this plugin is already injecting server_url.
Select any Repository and Pull Request event that should be processed by Jenkins. The above example shows the events that are automatically selected when generated by Bitbucket Branch Source as of version 2.4.0. See the supported events com.cloudbees.jenkins.plugins.bitbucket.hooks.HookEventType.java.
Save and ensure that the webhook has been properly created and is showing as "Active":
Important If the manual hook is not working, we encourage you to configure the Bitbucket Branch Source plugin to automatically create the webhooks in order to check which is the right URL to be used.
Any Version
Starting from Bitbucket Branch Source 2.3.0, you can choose between two webhook implementations: native or plugin.
For plugin implementation only:
The add-on Post Webhooks for Bitbucket can be installed to work with any version of Bitbucket Branch Source or Bitbucket Server. This add-on has been designed by the community to provide support to the Bitbucket Branch Source plugin with Bitbucket Server as part of JENKINS-33507. The source code of this add-on can be found on GitHub at https://marketplace.atlassian.com/apps/1215474/post-webhooks-for-bitbucket.
Once installed, this add-on adds a Post Webhooks section (Webhooks section for older version of the add-on) in the Settings of a repository. To create a Webhook for a repository, click on Add WebHook on the top right:
Give it any "title" and specify the Bitbucket Branch Source endpoint $JENKINS_URL/bitbucket-scmsource-hook/notify:
Select any Repository and Pull Request event that should be processed by Jenkins. The above example shows the events that are automatically selected when generated by Bitbucket Branch Source as of version 2.4.0. See the supported events com.cloudbees.jenkins.plugins.bitbucket.hooks.HookEventType.java.
Note: In older versions of the Post Webhooks for Bitbucket, the Repository and Pull requests events could not be selected and were defaulted to most of pull requests updates and repository pushes
Save and ensure that the webhook has been properly created and is not showing as "Inactive":
Troubleshooting
Please have a look at Bitbucket Webhooks Troubleshooting to troubleshoot issues with these solutions.