How to Trigger Multibranch Jobs from Bitbucket Cloud?

Article ID:115000051132
2 minute readKnowledge base

Issue

  • I want to configure Jenkins and Bitbucket Cloud 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 projects 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 cloud endpoints

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 cloud multibranch 2.2.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.

bitbucket cloud 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 cloud team project 2.2.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.

bitbucket cloud team project

Further Configuration

Once a project is saved, it automatically listens for events - commonly sent by webhooks - on the endpoint /bitbucket-scmsource-hook/notify.

You can enabled Manage Hooks 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 cloud endpoints

Older Versions

Prior to Bitbucket Branch Source 2.2.0, you can enable the option Auto-register webhook to let Jenkins automatically register a webhook for your repository/ies. This is the recommended, quicker, easiest configuration.

bitbucket scm auto hooks

Configuration in Bitbucket Cloud

If you have not setup Jenkins to automatically manage webhooks, see below to understand how to manually create the webhooks for you repositories:

Go to the Settings of a repository. Then go to the section Webhooks and click on Add Webhook:

bitbucket cloud webhooks

Give it the name you want and specify the Bitbucket Branch Source endpoint $JENKINS_URL/bitbucket-scmsource-hook/notify:

bitbucket cloud webhook add

Ensure that the webhook is created and enabled:

bitbucket cloud webhook added

From now on, Push and Pull Request events from that repository are notified to the Bitbucket Branch Source plugin.

Troubleshooting

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