How to Trigger Multibranch Jobs from BitBucket Server?

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

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

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.

You can enabled Manage Hooks for a specific under Manage Jenkins > Configure System > Bitbucket Endpoints to allow Jenkins to automatically register webhooks to that endpoint. This is the recommended, quicker, easiest configuration.

Older Versions

Before Bitbucket Branch Source 2.2.0 BUT since Bitbucket Branch Source 2.1.1 and Post Webhooks for Bitbucket 1.4.1 (bitbucket add-on), 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.

Note: Prior to Bitbucket Branch Source 2.1.1, the only workaround is to configure each repository hook manually in Bitbucket Server. But you can use the Bitbucket REST API to help you with that process, have a look at the article Generate webhooks in BitBucket Server via REST API for Pipeline Multibranch

Configuration in Bitbucket Server

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

You need to install the add-on Post Webhooks for Bitbucket. 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://github.com/topicusfinan/bitbucket-webhooks-plugin.

Once installed, this add-on adds a Webhooks section in the Settings of you repositories. To create a Webhook for a repository, click on Add WebHook on the top right:

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

Ensure that the webhook is created and enabled:

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.

References

Bitbucket Integration

Have more questions? Submit a request

11 Comments

  • 0
    Avatar
    K Caola

    The article is titiled "How to trigger Multibranch Jobs from BitBucket server" but the issue is "I want to configure Jenkins and BitBucket Cloud to automatically trigger Multibranch or Bitbcuket Team/Project jobs on changes". Then environment also lists BitBucket Server.

    Is that a typo?

    Or is this actually a how to for BitBucket Cloud AND NOT BitBucket Server?

  • 0
    Avatar
    Allan Burdajewicz

    Hi,

    You are right. This is a typo issue. This will be corrected soon.

    Thanks!

  • 0
    Avatar
    Nitul Kukadia

    @Allan Burdajewicz Please correct this typo issue. 

  • 0
    Avatar
    Denys Digtiar

    Hi Nitul,

    All the typos have already been corrected.

  • 0
    Avatar
    Nitul Kukadia

    Ok Allan Burdajewicz.

    Is this details are for BitBucket Cloud or Server?

  • 0
    Avatar
    Allan Burdajewicz

    Hi Nitul,

    This article is for Bitbucket Server integration.

  • 0
    Avatar
    Nitul Kukadia

    Thanks Allan,

    I configured integration successfully with server.

    Is there any official documentation for endpoint?URL: ENKINS_URL/bitbucket-scmsource-hook/notify

    I found JENKINS_URL/bitbucket-hook/  only.

  • 0
    Avatar
    K Caola

    Hi Nitul,

    I managed to get webhooks working using the "Bitbucket Server Webhook to Jenkins" plugin . When you use that you don't need a specific notify URL, just the main url for your jenkins server (such as http://<YourJenkinsServer>.com/). You can find it in one of the admin level panels, "Manage Jenkins" > "Configure System" > "Jenkins Location: Jenkins URL".

    If you have your jenkinsfile in a repository that does not have the webhooks (example, the webhook is in ProjectName repo and the jenkinsfile is in ProjectNameCI) then you need to check the "Omit Branch Name" box. If you have your jenkinsfile in a repository that has the webhooks then leave "Omit Branch Name" box unchecked.

    This is the setup that worked for us.
    For reference, I'm using Jenkins 2.46.1 and BitBucket server 5.5.1
    I hope this helps you!

     

    Edited by K Caola
  • 0
    Avatar
    David Norton

    Will support be added for X-Auth-Token header instead of HTTP Basic auth? Our BitBucket server is behind a single-sign-on provider and username/password auth is not available.

    UPDATE: our Bitbucket server uses the Token Authentication plugin here: https://marketplace.atlassian.com/plugins/com.thundermoose.plugins.stash-token-auth/server/overview

    Edited by David Norton
  • 0
    Avatar
    Roy Mammen

    Does the newer version of plugin supports ssh authentication? I would like to use ssh url (ssh://git@bitbucket.mycompany.com:7999/myproject/myrepo.git) instead of http url along with ssh private key from Jenkins credential store for authentication. Apparently the new plugin doesn’t allow me to choose ssh credentials from the credential drop down, and I also dont see the advance ssh port options within the Branch Source setup page within Jenkins. Is it by design? Or I am not looking at the right place?

    Thanks

  • 0
    Avatar
    Allan Burdajewicz

    Hello @Nitul, the endpoint `/bitbucket-scmsource-hook/notify` is not documented. The plugin was first designed to automatically create the webhook (and only for Bitbucket Cloud). And the documentation did not include reference to this endpoint. Something to improve.

    Hello @Roy, the Bitbucket Branch Source plugin uses the Bitbucket REST API to scan team project (Organization Scan) and branches (Branch Indexing). You can however use the SCM Trait "Checkout Over SSH" to use SSH for pipeline checkout.

    Hello @David, I believe Bitbucket Branch Source supports Personal Access Token authentication (added in Bitbucket Bucket Server 5.5). I am not sure about the Token Authenticator though. If this is a requirement, you could create an improvement issue in JIRA.

Please sign in to leave a comment.