|
Important
|
On March 5th, 2020, Atlassian releases Bitbucket Server 7 which removed some undocumented features related to pull requests.
|
Bitbucket Branch Source plugin allows use of Bitbucket Cloud and Server 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: This plugin is not compatible with versions of Bitbucket Server previous to 4.0.
Bitbucket Server 7.x is supported but does no longer support lightweight checkout for pull requests when merge strategy is used for build.
|
Important
|
In order to have the pull request process working the "Call Changes api" option must be enabled in Manage Jenkins » Configure System |
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 Server, 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 Server 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.
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 Server 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 relies on the configuration available via specific APIs provided by the Post Webhooks for Bitbucket plugin itself. To get it worked plugin must be already pre-installed on the server instance. This provider allows custom settings managed by the ignore committers trait. Note: This specific implementation will be moved to an individual repository as soon as JENKINS-74913 is implemented.
For both Bitbucket Multibranch Pipelines and Organization folders there is an "Override hook management" behavior 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 |
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 seperate SSH credential for checking out sources.
The plugin can make use of a personal access token (Bitbucket Server only) 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 repositories. 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.
Bitbucket deprecated usage of Atlassian account password for Bitbucket API and Git over HTTPS starting from March 1st, 2022 (Bitbucket Cloud only).
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. 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 plugin can make use of OAuth credentials (Bitbucket Cloud only) 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.
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 synchronized. 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.
In case of slow network, you can increase socket timeout using the Script Console:
System.setProperty("http.socket.timeout", "300") // 5 minutes