Skip to content

Latest commit

 

History

History
135 lines (94 loc) · 7.02 KB

USER_GUIDE.adoc

File metadata and controls

135 lines (94 loc) · 7.02 KB
Raw

CloudBees Bitbucket Branch Source plugin

Important

On March 5th, 2020, Atlassian releases Bitbucket Server 7 which removed some undocumented features with regards to pull requests.

  1. BitBucket Server Pipeline jobs can no longer perform a lightweight checkout of the Jenkinsfile if you are using the merge strategy for builds.

    1. BitBucket Server no longer stores the merged result of a PR to improve performance

    2. BitBucket Server Pipeline jobs will automatically fallback to heavyweight checkout

  2. BitBucket Server 7.x no longer automatically creates the required refs for pull requests

    1. For Bitbucket Server Pipeline jobs to function for pull requests on BitBucket Server 7.x you need to enable "Call Changes api" option in the plugin configuration

CloudBees Bitbucket Branch Source plugin (Bitbucket plugin up now) 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.

  • Team/Project 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 compatibility

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

Branches and pull requests auto-discovering

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:

  1. Create the multi-branch project. This step depends on which multi-branch plugin is installed. For example, "Multibranch Pipeline" should be available as project type if Pipeline Multibranch plugin is installed.

    screenshot 1

  2. Select "Bitbucket" as Branch Source

    screenshot 2

  3. Set credentials to access Bitbucket API and checkout sources (see "Credentials configuration" section below).

  4. Set the repository owner and name that will be monitored for branches and pull requests.

  5. If using Bitbucket Server the server base URL needs to be configured (expand the Advanced section to do it).

    screenshot 4

  6. Finally, save the project. The initial indexing process will run and create projects for branches and pull requests.

    screenshot 5

Team folders

Bitbucket Team/Project Folders project type can be used to automatically track branches and pull requests in all repositories in a Bitbucket Team or Project.

  1. Create a project of type Bitbucket Team/Project. The project name will be proposed automatically as default Owner (or Team) name.

    screenshot 6

  2. Configure the repository owner (if the proposed value does not match with the actual team or username). It could be:

    1. A Bitbucket Cloud Team name: all repositories in the team are imported as Multibranch projects.

    2. 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.

    3. A regular username: all repositories which the username is owner of are imported.

      screenshot 8

  3. Save the configuration and an initial indexing process starts, once it finishes a Multibranch project is created for each repository.

    screenshot 9

Webhooks registering

The use of Bitbucket webhooks allows to trigger builds on branches and pull requests just when a new commit is done. Bitbucket plugin expose a special service to listen to this webhook requests and acts accordingly by triggering a new reindex and finally triggering builds on matching branches or pull requests.

For both Bitbucket Multibranch projects and Bitbucket Team projects there is an option in the configuration page to let Jenkins to automatically register the webhooks in all involved repositories.

screenshot 4
Important
 In order to have the auto-registering process working fine the Jenkins base URL must be properly configured in Manage Jenkins » Configure System

Credentials configuration

The configuration of Bitbucket plugin (for both Bitbucket Multibranch projects and Bitbucket Team/Project) has two credentials to configure:

  1. Scan Credentials: credentials used to access Bitbucket API in order to discover repositories, branches and pull requests. If not set then anonymous access is used, so only public repositories, branches and pull requests are discovered and managed. Note that the Webhooks auto-register feature requires scan credentials to be set. Only HTTP or OAuth credentials are accepted in this field.

  2. Checkout Credentials: credentials used to checkout sources once the repository, branch or pull request is discovered. HTTP, SSH and OAuthcredentials are allowed. If not set then Scan Credentials are used.

screenshot 3

OAuth credentials

Bitbucket plugin can make use of OAuth credentials instead of the standard username/password.

First create a new OAuth consumer as instructed in Bitbucket OAuth Documentation. Don’t forget to check This is a private consumer and at least allow read access to the repositories and Pull requests. If you want the Bitbucket to install the Webhooks also allow the read and write access of the Webhooks

screenshot 10

Then create new Username with password credentials, enter the Bitbucket OAuth consumer key in Username field and the Bitbucket OAuth consumer secret in Password field

screenshot 11
screenshot 12

Miscellaneous configuration

In case of slow network, you can increase socket timeout using the Script Console :

System.setProperty("http.socket.timeout", "300") // 5 minutes