How to Trigger Multibranch Jobs from Bitbucket Server?

Article ID:115000053051
4 minute readKnowledge base

Issue

  • I want to configure Jenkins and Bitbucket Server to automatically trigger Multibranch or Bitbucket Team/Project jobs on changes

Environment

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 Manage Jenkins  Configure System  Bitbucket Endpoints:

bitbucket server endpoints 2.3.0

Multibranch Project

To track a single repository, create an item of type Multibranch Pipeline and use the Bitbucket branch source:

mutlibranch branch source

Configure the SCM Source (refer to the help tooltips of each Behavior to better understand what it does):

bitbucket server multibranch 2.3.0

Older Versions

Prior to Bitbucket Branch Source 2.2.0, there is nothing to configure in Manage Jenkins  Configure System. 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 server multibranch

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:

orgfolder repository source

Configure the SCM Source (refer to the help tooltips of each Behavior to better understand what it does):

bitbucket server team project 2.3.0

Older Versions

Prior to Bitbucket Branch Source 2.2.0, there is nothing to configure in Manage Jenkins  Configure System. 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 server team project

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 Manage Jenkins  Configure System  Bitbucket Endpoints to allow Jenkins to automatically register webhooks to that endpoint. This is the recommended, quicker, easiest configuration.

bitbucket server endpoints 2.3.0

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.

bitbucket scm auto hooks

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":

bitbucket server webhooks native

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:

bitbucket server webhook native add

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":

bitbucket server webhook plugin added

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:

bitbucket server webhooks plugin

Give it any "title" and specify the Bitbucket Branch Source endpoint $JENKINS_URL/bitbucket-scmsource-hook/notify:

bitbucket server webhook plugin add

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":

bitbucket server webhook plugin added

Troubleshooting

Please have a look at Bitbucket Webhooks Troubleshooting to troubleshoot issues with these solutions.