Bitbucket Branch Source plugin allows use of Bitbucket Cloud and Data Center as a multi-branch project source in two different ways:
-
Single repository source: automatic creation of jobs for branches and pull requests in a specific repository.
-
Organization folders: automatic creation of multi-branch projects for each visible repository in a specific Bitbucket Team or Project.
|
Important
|
Since version 937.0.0 this plugin officially supports only versions of Bitbucket Data Center not excluded by the End Of Support (EOS) policy. |
This plugin adds an additional item in the "Branch Sources" list of multi-branch projects. Once configured, branches and pull requests are automatically created and built as branches in the multi-branch project.
Follow these steps to create a multi-branch project with Bitbucket as a source:
-
If using Bitbucket Data Center, the server base URL needs to be added to the Bitbucket Endpoints first in the "Manage Jenkins" > "System" configuration.
-
Create the multi-branch project. This step depends on which multi-branch plugin is installed. For example, "Multibranch Pipeline" should be available as a project type if Pipeline Multibranch plugin is installed.
-
Select "Bitbucket" as Branch Source
-
Set credentials to access Bitbucket API and checkout sources (see "Credentials configuration" section below).
-
Set the repository owner and name that will be monitored for branches and pull requests.
-
Finally, save the project. The initial indexing process will run and create projects for branches and pull requests.
Bitbucket Team/Project Repository Source can be used in Organization Folder to automatically track branches and pull requests in all Bitbucket Team or Project repositories.
-
Create a project of type Organization Folder.
-
Add Bitbucket Team/Project as Repository Source
-
If you configured more than one Bitbucket Endpoint, choose the Server and appropriate Credential
-
Configure the repository owner. It could be:
-
A Bitbucket Cloud Workspace ID (aka workspace slug): all repositories in the workspace are imported as Multibranch projects.
-
A Bitbucket Data Center Project ID: all repositories in the project are imported as Multibranch projects. Note that the project ID needs to be used instead of the project name.
-
A regular username: all repositories which the username is owner of are imported.
-
-
Save the configuration. The initial indexing process starts. Once it finishes, a Multibranch project is created for each repository.
This plugin have customized icon designed for the "Organization Folder" 
, for "Multibranch Pipeline", for Single Repository 
and Folder 
project type. This is the default behaviour of the plugin starting from version 935.
It is possible associate the Bitbucket avatar to the project item selecting the "Show Bitbucket avatar images" behaviour in the project configuration.
The supported avatars are:
-
Organization Folder:
-
Cloud: workspace avatar
-
Data Center: project avatar
-
-
Multibranch Repository:
-
Cloud: repository avatar
-
Data Center: does not support customization of the repository avatar
-
The default Bitbucket avatar is a generated SVG image, since this plugin does not support SVG format, this image will be replaced by a Jenkins random generated image.
The use of Bitbucket webhooks allows to trigger builds on branches and pull requests just when a new commit is done. Bitbucket plugin exposes a special service to listen to these webhook requests and acts accordingly by triggering a new reindex and finally triggering builds on matching branches or pull requests.
Go to "Manage Jenkins" / "System" and locate Bitbucket Endpoints. For every endpoint where you want webhooks registered automatically, check "Manage hooks" and select a "Credential" with enough access to add webhooks to repositories. Since the Credential is used at the system level, it can be a System scoped credential, which will restrict its usage from Pipelines. You can setup a custom Jenkins URL to be used as callback URL by the webhooks.
For Bitbucket Data Center only, it is possible chose which webhooks implementation server side to use:
-
Native implementation will configure the webhooks provided by default with the Server, so it will always be available.
-
Plugin implementation (deprecated) replaced by this plugin
-
Any other extension point implementation installed in your Jenkins instance
For both Bitbucket Multibranch Pipelines and Organization folders there is an "Override hook management" behaviour to opt out or adjust system-wide settings.
|
Important
|
In order to have the auto-registering process working fine the Jenkins base URL must be properly configured in Manage Jenkins » System, in alternative the URL must be provided in the endpoint configuration. |
Once Jenkins is configured to receive payloads, it will listen for any delivery that’s sent to the endpoint you configured. For security reasons, you should only process deliveries from Bitbucket. To ensure your self-hosted server only processes deliveries from Bitbucket, you need to:
-
Create a secret token for a webhook
-
Enable hooks signature verification for the chosen Bitbucket Endpoints
-
Select the secret token create at point 1, only String credentials are taken into account.
Any incoming webhook payloads from that given endpoint will be validated against the configured token, to verify they are coming from the configured Bitbucket endpoint URL.
If your organisation has a large number of repositories (over 500), you may easily reach the API rate limit. Any requests made to Bitbucket beyond 1,000 per hour will be rejected. In this case, enable caching to allow webhooks from repositories beyond the 500th to be processed within the next hour (when the rate is unlocked).
See JENKINS-76184 for the use case.
If your organisation does not allow credentials to handle repository webhooks than you can provide to register webhook manually. You can follow one of these official Atlassian guides: for Cloud or for Data Center.
Go to the Bitbucket Repository » Repository settings » Webhooks than _Add Webhook
Provide a title of your choice, if you generate a secret for payload verification than confiure signature verification in Bitbucket endpoint as in the previous chapter.
Select events as shown in the image; any other types selected will be ignored.
The callback URL must be configured as follow: * Cloud: <Jenkins root URL>/bitbucket-scmsource-hook/notify * Server: <Jenkins root URL>/bitbucket-scmsource-hook/notify?server_url=<Bitbucket Data Center URL>
The <Jenkins root URL> must match the Jenkins public host; if Jenkins is behind a reverse proxy, ensure the URL provided matches the one in Manage Jenkins » System » Jenkins Location. In other cases, you can provide the Jenkins root URL to use, in the webhook configuration page on the Bitbucket endpoint. The <Bitbucket Data Center URL> must match the server address configured in the Bitbucket endpoint. Otherwise, incoming webhooks will be discarded.
The plugin (for both Bitbucket multibranch pipelines and Bitbucket Workspace/Project organization folders) requires a credential to be configured to scan branches. It will also be the default credential to use when checking out sources.
As the Checkout Credential configuration was removed in commit (a4c6bf3), you can alternatively add a Checkout over SSH behavior in the configuration of Behaviours, so that to configure a separate SSH credential for checking out sources.
Bitbucket searches for all credentials that implement StandardCredentials (the most generic) and determines which ones fit one of the types described below, also based on the server type (endpoint) selected. Some credential implementations require a remote call to a vault (such as AWS, Azure, etc.), which takes time. When many of these credentials are present, the Jenkins UI configuration page may time out. To avoid this type of issue, the best practice is to register all Bitbucket credentials in a specific credential domain.
And configure a specification to restrict credentials using for example a hostname specification as in the image:
It works because whenever this plugin lists the credentials available in the system, it automatically adds a specification based on the URL of the selected Bitbucket endpoint.
The plugin can use a personal username and password to login (if SSO and MFA in not enabled).
The user must have admin access to the Project if you are configuring an Organization Folder or admin right to the repositories if you are configuring a Multibrach Project.
The plugin can make use of a personal access token instead of the standard username/password.
First, create a new personal access token in Bitbucket as instructed in the HTTP access tokens | Bitbucket Data Center and Server 8.0 | Atlassian Documentation. At least allow read access for Projects. If you want the plugin to install the webhooks, allow admin access for repositories.
Then create a new Username with password credential in Jenkins, enter the Bitbucket username (not the email) in the Username field and the created access token in the Password field.
The plugin can make use of a repository, project or workspace access token.
First, create a new access token in Bitbucket as instructed in one of the following links:
At least allow read access for repositories. If you want the plugin to install the webhooks, allow Read and write access for Webhooks.
Then create a new Secret text credential in Jenkins, enter the Bitbucket token generated in the previous steps in the Secret field.
If you want be able to perform git push operation from CLI than you have to setup write access for repositories. Than configure the Custom user name/e-mail address trait with the Repository Access Token email generated when you created the Repository Access Token (for example, 52c16467c5f19101ff2061cc@bots.bitbucket.org).
Bitbucket deprecated usage of Atlassian account password for Bitbucket API and Git over HTTPS starting from March 1st, 2022.
The plugin can make use of an app password instead of the standard username/password.
First, create a new app password in Bitbucket as instructed in the Bitbucket App Passwords Documentation. At least allow read access for repositories and pull requests. Also, you may need to allow read and write access for webhooks depending on your pipeline’s triggers.
Then create a new Username with password credentials in Jenkins, enter the Bitbucket username (not the email) in the Username field and the created app password in the Password field.
|
Important
|
App passwords do not support email address as a username for authentication. Using the email address will raise an authentication error in scanning/checkout process. |
The app passoword authentication has been deprecated by Atlassian and starting from September 9th, 2025 will not longer available for creation. Read here for more informations.
Bitbucket deprecated usage of Atlassian App Password for Bitbucket API and Git over HTTPS starting from September 9th, 2025.
The plugin can make use of an user API token with scopes instead of the app password.
First, create a new User API token in Bitbucket as instructed in the Bitbucket API Token Documentation. At least allow read access for project, repositories and pull requests. Also, you may need to allow read and write access for webhooks depending on your pipeline’s triggers.
Then create a new Username with password credentials in Jenkins, enter the Atlassian Account email (not the username) in the Username field and the created API token in the Password field.
|
Important
|
API token requires the email address as a username to authenticate using the BitbucketAPIs. Using the username will raise an authentication error in scanning/checkout process. API token without scope does not work. |
The plugin can make use of OAuth credentials instead of the standard username/password.
First create a new OAuth consumer in Bitbucket as instructed in the Bitbucket OAuth Documentation. Don’t forget to check This is a private consumer and at least allow read access for repositories and pull requests. If you want the plugin to install the webhooks, also allow read and write access for webhooks.
Then create new Username with password credentials in Jenkins, enter the Bitbucket OAuth consumer key in the Username field and the Bitbucket OAuth consumer secret in the Password field.
A mirrored Git repository can be configured for fetching references. This feature is available only on Bitbucke Data Center.
The mirror is not used in the following cases:
-
If the source branch in a pull request resides in a different repository, the source branch is fetched from the primary repository while the target branch is fetched from the mirror.
-
During initial pull request scanning, the mirror isn’t used because of the current design limitations.
Cloning from the mirror can only be used with native web-hooks since plugin web-hooks don’t provide a mirror identifier.
For branches and tags, the mirror sync event is used. Thus, at cloning time, the mirror is already synchronised. However, in the case of a pull request event, there is no such guarantee. The plugin optimistically assumes that the mirror is synced and the required commit hashes exist in the mirrored repository at cloning time. If the plugin can’t find the required hashes, it falls back to the primary repository.
When a new job build starts, the plugin send notifications to Bitbucket about the build status. An "In progress" notification is sent after complete the git checkout, another notification is sent at the end of the build, the sent value depends by the build result and the configuration given by the trait.
Follow a summary of all possible values:
| Jenkins | Bitbucket Cloud | Bitbucket Data Center |
|---|---|---|
SUCCESSFUL |
SUCCESSFUL |
|
configurable SUCCESSFUL or FAILED |
configurable SUCCESSFUL or FAILED |
|
FAILED |
FAILED |
|
configurable FAILED or STOPPED |
configurable FAILED or CANCELLED |
|
configurable FAILED or STOPPED |
configurable FAILED or CANCELLED |
|
null |
INPROGRESS |
INPROGRESS |
The STOPPED status prevents merge checks on Cloud, CANCELLED status should prevents merge checks on Data Center
If this does not meet you need you can disable any notification to Bitbucket using the skip-notifications-trait-plugin and provide notification about the build status yourself. This can be achieved via a curl shell command or by using build steps provided by the bitbucket-build-status-notifier-plugin.
This plugin contribute to the enviroment the following variables:
-
BITBUCKET_REPOSITORY: the repository name/slug
-
BITBUCKET_OWNER: the repository owner name/slug, in Bitbucket Cloud is the equivalent of workspace name
-
BITBUCKET_PROJECT_KEY: the project key in which the repository is contained
-
BITBUCKET_SERVER_URL: the Bitbucket endpoint URL
These variables were added to allow users to easily integrate calls to Bitbucket’s REST APIs into their own pipelines to implement own business logics.
|
Note
|
Since variables are contributed through a GitSCMExtension they will be available only after performed the checkout scm step. For the same reason existing projects must be updated with a "Scan Organization Folder Now" or "Scan Multibranch Project Now" action to persist the new git extension in the job configuration. |
In case of slow network, you can increase socket timeout using the Script Console:
System.setProperty("http.socket.timeout", "300") // 5 minutesIn case Bitbucket has been configured to expire OAuth2 tokens before 5 minutes, you can configure via a JVM property the release time of the cache where all obtained OAuth2 tokens are stored. This setting is to avoid requests with expired tokens that will produce HTTP 401 responses. Bitbucket Cloud access tokens expire in two hours.
To change this amount of time (default is 300 seconds), add the system property bitbucket.oauth2.cache.timeout=60 on Jenkins startup.
By default, the plugin does not triggers a full branch indexing when a push event contains empty changes. This may happen on various scenario, mainly in Bitbucket Data Center, such as:
-
When manually merging remote Open pull requests. This particular scenario produces 2 events and cause duplicated builds.
-
For a fork, when Auto-Sync is on and a branch cannot be synchronised
-
A mirror:repo_synchronized event with too many refs
This behaviour can be enabled by adding the system property bitbucket.hooks.processor.scanOnEmptyChanges=true on Jenkins startup.