Jenkins : Bitbucket Branch Source Plugin

Plugin Information

View Bitbucket Branch Source on the plugin site for more information.

Multibranch projects and Team/Project folders from Bitbucket Cloud and Server. Please note that this plugin requires a server running BitBucket 5.2.0 or later; Stash 3.x and earlier are not supported.


User guide

Configure plugin via Groovy script

Either automatically upon Jenkins post-initialization or through Jenkins script console, set Jenkins Bitbucket Cloud Endpoint global configuration to manage hooks, example:


// imports
import com.cloudbees.plugins.credentials.*
import com.cloudbees.plugins.credentials.impl.*
import hudson.util.Secret
import jenkins.model.Jenkins
import com.cloudbees.jenkins.plugins.bitbucket.endpoints.*

// parameters
def bitbucketEndpointKeyParameters = [
  description:  'Bitbucket Cloud Endpoint Key',
  id:           'bitbucket-cloud-endpoint-key',
  secret:       '12345678901234567890',
  userName:     'my-bitbucket-username-here'

def bitbucketEndpointParameters = [
  manageHooks:   true,

// get Jenkins instance
Jenkins jenkins = Jenkins.getInstance()

// get credentials domain
def domain =

// get credentials store
def store = jenkins.getExtensionList('com.cloudbees.plugins.credentials.SystemCredentialsProvider')[0].getStore()

// define Bitbucket secret
def bitbucketCloudKey = new UsernamePasswordCredentialsImpl(

// add credential to store
store.addCredentials(domain, bitbucketCloudKey)

// get Bitbucket endpoint configuration
def bitbucketEndpoint = jenkins.getDescriptor("com.cloudbees.jenkins.plugins.bitbucket.endpoints.BitbucketEndpointConfiguration")

// define Bitbucket cloud endpoint
def bitbucketCloudEndpoint = new BitbucketCloudEndpoint(

// update endpoint

// save to disk

Version History - Moved to

Version 2.4.2 (February 19, 2019)

  • JENKINS-46094 - "Checkout over SSH" fails the build since it still uses HTTPS urls Closed

Version 2.4.1 (January 31, 2019)

  • JENKINS-40958 - Allow pullrequest approved in webhooks for bitbucket multibranch projects Open
  • JENKINS-55423 - Support optional custom Jenkins server URL value when registering a webhook Resolved

Version 2.4.0 (January 14, 2019)

  • Updated to Java 8 and Jenkins 2.60.3
  • Updated dependency on Jsch library to Jsch plugin 0.1.55 to fix directory traversal vulnerability on windows
  • Updated description to reflect support for Bitbucket Server

Version 2.3.0 (December 27, 2018)

  • Native webhooks for Bitbucket server, thanks to Unknown User (twz123) 
    JENKINS-46946 - Use the bitbucket server webhook api Closed
    JENKINS-47891 - Bitbucket branch source plugin does not understand the new Bitbucket Server webhooks Resolved

Version 2.2.16 (December 18, 2018)

  • JENKINS-55068 - Multibranch scanning deletes jobs if bitbucket server goes away during scan Resolved  Only consider 404 as path does not exist when scanning repositories
  • #158 http client should now respect system properties

Version 2.2.15 (November 18, 2018)

  • JENKINS-54401 - NPE when parsing scm git revision date on PR branches Resolved  fix null pointer when parsing git revision date

Version 2.2.14 (October 31, 2018)

Version 2.2.13 (October 27, 2018)

  • JENKINS-47283 - Allow for different HTTP & SSH endpoint URIs Resolved  Allow for different HTTP & SSH endpoints
  • JENKINS-51196 - Display caches statistics in servers global configuration Resolved  Add statistics for caches in global configuration on Bitbucket cloud endpoints.
  • JENKINS-47617 - CHANGE_BRANCH no longer reporting branch name, but instead PR Resolved  CHANGE_BRANCH should now return source branch name
  • JENKINS-52138 - Change the BitBucket status message for "In progress" builds Resolved  Status message now reads "The build in progress" when build is running instead of "The tests have started"
  • JENKINS-52134 - Build status is not sent to Mercurial repo on BitBucket Resolved  Build Status should now be sent for Mercurial repo
  • JENKINS-51063 - Multibranch pipeline does not handle correctly webhook of kind tag created Resolved  handle tag events sent from webhook correctly
  • #127 Adding Bitbucket repository information to request to allow traits to filter by project
  • #130 Notify Bitbucket Status only once
  • #131 #146 Fix bad Jenkins root URL for Bitbucket API
  • #135 Restore timeouts in BitbucketServerAPIClient
  • #136 CHANGE_AUTHOR_EMAIL environment variable now available
  • #141 Allow build description to be passed to Bitbucket Status notification
  • #147 Use project name instead of job name as key in Bitbucket server's status notification
  • #149 Fix potential null pointer

Version 2.2.12 (July 5, 2018)

  • JENKINS-45997 - BitBucket PRs failing to checkout on initial run after PR updated with new commits Resolved  Check mergability when retrieving pull requests
  • JENKINS-50314 - Using or not caches should be configurable in servers global configuration Closed  Using or not caches (for teams and repositories) is now configurable

Version 2.2.11 (April 25, 2018)

  • JENKINS-45860 - Support traits for ScmNavigators Closed  Job DSL compatibility
  • JENKINS-49671 - Can't configure jenkinsfile in subdirectory Closed  Allow the use of Jenkinsfile in a folder
  • JENKINS-49709 - Proxy Config broken in Bitbucket Branch Source Plugin Closed  Fixes a proxy configuration issue
  • JENKINS-47254 - Support for building tags for Bitbucket Server/Cloud Closed  Support tags discovering

Version 2.2.10 (Febuary 16, 2018)

  • JENKINS-47958 - Closed branches clone again and try build Resolved  Filter closed Hg branches out

Version 2.2.9 (January 24, 2018)

  • Switched to using Handy Uri Template
  • Added cache to limit BitBucket API rate hits
  • JENKINS-48206 - Upgrade to HttpClient 4.x in Bitbucket branch source Resolved  Upgraded to HttpClient 4.x
  • JENKINS-47978 - Lightweight checkout not working for branches that contain forward slash '/' Resolved  Fixed handling branch name with '/'

Version 2.2.8 (December 18, 2017)

  • Add ability for extension plugins to modify webhook creation / update process
  • Sort the list of repository names alphabetically
  • Fixed spelling error in job configuration form validation
  • Remove limit of 100 API pages when scanning repositories with very many branches
  • JENKINS-48279 - GetDirectoryContent does not increase size/page number Resolved  Correctly list contents of directory when there is more than one API page
  • JENKINS-47653 - Bitbucket Branch Source v2.2.4 introduces long delay in starting builds Resolved  Make fetching the timestamp of a branch lazy (most users do not need the information and fetching always was negatively impacting checkout performance)
  • JENKINS-45836 - Repositories you contribute to but don't own won't appear in Branch Source Plugin Resolved  Allow contributors to select repositories that they contribute to
  • JENKINS-45891 - Cannot merge PRs from private, forked repositories Resolved  Fix incorrect checkout of PRs from private forked repositories on Bitbucket server 
  • JENKINS-47978 - Lightweight checkout not working for branches that contain forward slash '/' Resolved  Fix lightweight checkout when things have / in them
  • JENKINS-38664 - bitbucket source plugin fails with bad URL Resolved  Skip notification if Jenkins does not have a root URL configured

Version 2.2.7 (November 9, 2017)

  • Fix UnknownFormatConversionException introduced in 2.2.6

Version 2.2.6 (November 8, 2017)

  • JENKINS-42518 - Provide lightweight checkout capability for bitbucket to avoid repository clone for multi-branch pipeline jobs Resolved  Provide lightweight checkout capability for bitbucket to avoid repository clone for multi-branch pipeline jobs
  • JENKINS-47824 - git plugin 3.6.3 lost support for tagged pipeline shared libraries Closed  If GitSCMSource gives us a GitTagSCMHead try not to turn it into a branch

Version 2.2.5 (November 1, 2017)

  • JENKINS-47675 - Events are not processed correctly, no builds until you hit scan. Open  Fix regression in push event notification for PRs on Bitbucket Server
  • JENKINS-45497 - Move BitbucketCloudApiClient to Bitbucket v2 Closed  Switch Bitbucket Cloud to v2 api

Version 2.2.4 (October 20, 2017)

  • PR#62 Fix project/team URL in BitbuckerServer
  • PR#47 Use full build name instead of name for status notifications
  • PR#65 Added a simple sleep and retry loop when rate limiting occurs
  • PR#67 Expose branch tip modification timestamps to extension plugins
  • JENKINS-45775 - Unable to build PR from private fork in BitbucketServer Open  Unable to build PR from private fork in BitbucketServer
  • PR#70 Implement missing SCMHead.getPronoun() override

Version 2.2.3 (July 28, 2017)

  • JENKINS-45771 - Disable shallow clone when we know a merge will take place Open  Disable shallow clone when we know a merge will take place

Version 2.2.3 (July 28, 2017)

  • JENKINS-45771 - Disable shallow clone when we know a merge will take place Open  Disable shallow clone when we know a merge will take place

Version 2.2.2 (July 20, 2017)

  • JENKINS-45632 - Handle when default branch is not found Resolved  Handle when default branch is not found
  • JENKINS-45676 - When creating a new bitbucket team, the default traits are not populated Closed  Default traits were not populated for newly created Bitbucket teams

Version 2.2.1 (July 18, 2017)

  • JENKINS-45343 Titles within inline help for Behaviors should match the titles in the dropdown

Version 2.2.0 (Jul 17, 2017)

  • JENKINS-43507 Allow SCMSource and SCMNavigator subtypes to share common traits
  • JENKINS-45533 Bitbucket webhook push notification are ignored on trait implementation
  • JENKINS-41190 Bitbucket Cloud API Implementation uses incorrect domain names
  • JENKINS-45467 On upgrade to 2.2.x, if the username password used as checkout credentials then configuration is migrated to an empty SSH Checkout behaviour
  • JENKINS-45436 API to generate (mostly) human readable names of SCM server URLs
  • JENKINS-45434 Add an avatar cache so that SCMs that providing fixed size avatars can convert to Jenkins native sizes
  • JENKINS-45344 Duplicate entries in Trust dropdown
  • JENKINS-43433 Allow SCMSource implementations to expose merge and origin of change request heads
  • JENKINS-44413 Replace configuration of the SSH port with detection from the clone links
  • JENKINS-36890 PR's do not meet the criteria when Include Branches is set

Version 2.1.2 (Mar 16, 2017)

  • JENKINS-42795 Incorrect type mapping of href deserialization in team objects from Bitbucket Cloud

Version 2.1.1 (Mar 9, 2017)

Version 2.1.1-beta-1 (Mar 8, 2017)

Version 2.1.0 (Feb 15, 2017)

  • JENKINS-36029 If there is an API error connecting to BitBucket, do not delete/mark as orphaned all the branches in a multi-branch project in retaliation.
  • JENKINS-42000 If there is an API error connecting to BitBucket, do not delete/mark as orphaned all the projects in an organization folder in retaliation. NOTE: requires an upgrade to Branch API 2.0.6+ to get the complete fix.

Version 2.0.2 (Feb 2, 2017)

  • JENKINS-41464 Contributor metadata action items missing on PRs after index
  • JENKINS-41313 On first index after upgrade to 2.0.0 all open PRs are rebuiltOn first index after upgrade to 2.0.0 all open PRs are rebuilt

Version 2.0.1 (Jan 23, 2017)

Version 2.0.0 (Jan 16, 2017)

Version 1.9 (Dec 28, 2016)

  • Honor non-proxy hosts (JENKINS-39297)
  • Build status API identifier (key) was too long so Bitbucket rejects the request (JENKINS-36874)

Version 1.8 (Sep 20, 2016)

Version 1.7 (Apr 12, 2016) 

  • Bug fix: limited to 25 branches because of pagination.
  • New feature: commit status notifications: In progress.

Version 1.5 (Apr 12, 2016) 

  • New Item categorization support (Jenkins 2.0 readiness).

Version 1.4 (Mar 13, 2016)

  • Initial OSS release.