This is the configuration guide for people who use the Bitbucket Branch Source Plugin in Jenkins. If you use the Git Plugin, see here.

If you have not already downloaded the plugin, you can get it here

Using Git’s post-receive hooks, it’s possible to trigger builds on Jenkins after a commit. There is a little configuration required in both Jenkins and Bitbucket.

Configuring Jenkins

  1. Install the Bitbucket Branch Source plugin in Jenkins.

  2. Go to Manage Jenkins → Configure System. Scroll down to Bitbucket Endpoints.

  3. Click the Add button and select Bitbucket Server from the dropdown.
  4. Enter the name and URL for your endpoint. If you have a Manage Hooks checkbox, make sure it's unchecked.

Configuring your Jenkins Job

You can use either the Multibranch Pipeline job or the Bitbucket Team job with the plugin. Both configurations are very similar. Here's an example:

  1. On the Job configuration screen, scroll down to the Branch Sources section (for a Bitbucket Project configuration, this section is called Projects).
  2. Click the Add Source button and select Bitbucket.
  3. For server, select the Bitbucket Server endpoint you added before (see Configuring Jenkins above).
  4. Add your administrator Bitbucket credentials if you have not already, and select them.
  5. For owner, put either the Bitbucket project or username which the repository is hosted under.
  6. You're done!

Configuring Bitbucket

Configuring on a per Repository Basis

  1. In Bitbucket, install Webhook to Jenkins for Bitbucket.
  2. Navigate to your repository and hit the Repository Settings tab. 
  3. In the left-side navigation, click the Hooks link. 
  4. Select Enabled from the dropdown for the Post-Receive hook, Bitbucket Server Webhook to Jenkins. 

    Versions of Bitbucket prior to 5.2.0 will not have a dropdown, and instead will just have a toggle.

    If you're using Bitbucket 5.2.0+ and you've already setup a project configuration that you would like to use, you can select Inherited and stop here.


  5. Enter the URL for your Jenkins instance and the Repository URL that you configured Jenkins to use. You can use the dropdown to get the clone URL for each supported protocol. Afterwards, feel free to change it to match your Jenkins instance. 
  6. Make sure you select the Bitbucket Branch Source Plugin as the Jenkins endpoint.
  7. Click the Trigger Jenkins button to test your configuration. If it worked, it’d look like this: 

That’s it!

With both Jenkins and Bitbucket now configured, if you commit code, a build trigger will automatically occur. What happens is the post-receive hook fires a GET request to Jenkins, which then tells it to poll the repository. The poll checks to see if there are actually any changes. Since there are, it triggers the build!

Configuring on a per-Project Basis

  1. In Bitbucket, install Webhook to Jenkins for Bitbucket.
  2. Navigate to your project and hit the Project Settings tab. 
  3. In the left-side navigation, click the Hooks link. 
  4. Toggle the Post-Receive hook, Bitbucket Server Webhook to Jenkins to Enabled.


  5. Enter the URL for your Jenkins instance and the Repository URL that you configured Jenkins to use. You can use the dropdown to get the clone URL for each supported protocol. Afterwards, feel free to change it to match your Jenkins instance. Make sure you include the {repository} field so Jenkins knows where to add repository id for the URL.

  6. Click the Trigger Jenkins button to test your configuration. If it worked, it’d look like this: 

That’s it!

With both Jenkins and Bitbucket now configured, if you commit code, a build trigger will automatically occur. What happens is the post-receive hook fires a GET request to Jenkins, which then tells it to poll the repository (why you need to have polling turned on). The poll checks to see if there are actually any changes. Since there are, it triggers the build!