Jenkins Bitbucket Integration

Published: Wednesday, 24 June 2020

Triggering a build after a pull request has been merged

A development workflow might consist of feature branches that are only merged via a pull request (PR) from Bitbucket Cloud. After the PR is merged, Jenkins should be notified to trigger a build.

It is possible configure Jenkins and Bitbucket Cloud to accomplish this.

Configuration steps

  1. Jenkins: plugin: Generic Webhook Trigger

    Navigate to Jenkins → Manage Jenkins → Manage Plugins

    Install the Generic Webhook Trigger Plugin

  2. Jenkins: Create an auth token for Bitbucket

    Create a new Jenkins user, e.g. bitbucket. It will be used to trigger the job. Alternatively you can use an existing user.

    Login with the user → Profile (top right icon) → Configure

    Navigate to API Token → Current token(s) → Add new Token

    Remember the chosen user and token value.

  3. Jenkins: Configure the job’s trigger

    Navigate to the job and click on ConfigureBuild Triggers

    Check Generic Webhook Trigger

    Add parameters that determine whether the job should be triggered.

    In this example we need

    • Post content parameters → Add a Variable with name branch, with Expression equal to $ and JSONPath checked.

    • Post content parameters → Add a Variable with name repository_name, with Expression equal to $.pullrequest.destination.repository.full_name and JSONPath checked.

    • Header parameters → Add a Request header with value X-Event-Key, and empty Value filter.

    Configure the Generic Webhook Trigger

    Configure the Generic Webhook Trigger X-Event-Key

    Other parameters can be used by using expressions that extract values from the HTTP POST webhook request coming from Bitbucket Cloud.

    All jobs work on the same endpoint. To specify whether a job should be triggered based on the webhook request, use the parameters in the Optional filter.

    Optional filter → Text $branch $repository_name $x_event_key.

    Optional filter → Expression master magicmonster/example-repo pullrequest:fulfilled

    The above Optional filter will perform a text match, and will only trigger when a pull request is merged (pullrequest:fulfilled) into the master branch of the magicmonster/example-repo repository.

    These parameters are set as environment variables and can be used during the build.

  4. Jenkins: open firewall

    Allow Bitbucket Cloud to access. See the wiki for IP addresses or view them as JSON.

  5. Bitbucket Cloud: Configure a webhook

    Navigate to

    Target repository → Repository Settings → Workflow → Webhooks

    There may be existing read only Webhooks, such as Pull Request Commit Links, Pipelines, Bitbucket code search. These are internal to bitbucket and can be ignored.

    Click on Add webhook and enter in

    Title: Jenkins PR merged

    URL: https://JENKINS_USER:TOKEN@JENKINS_HOST_PORT/generic-webhook-trigger/invoke where JENKINS_HOST_PORT is the public Jenkins host and port, JENKINS_USER and TOKEN is the user chosen and token generated in step 2.

    Status: Active

    Triggers: Choose from a full list of triggers Pull Request: merged

Alternative configuration using a job token

An alternative to parameter matching is to set a known token for each job.

Skip step 2.

In step 3, configure the job by navigating to the job and clicking on ConfigureBuild Triggers

Check Generic Webhook Trigger

Set Token to secret-job-token-foo or another value. Do not configure any other trigger parameters.

Configure the Generic Webhook Trigger using a token

In step 5, append the request parameter ?token=secret-job-token-foo to the URL. The job token is different to the Jenkins authentication token.

Set URL to https://JENKINS_HOST_PORT/generic-webhook-trigger/invoke?token=JOB_TOKEN where JENKINS_HOST_PORT is the public Jenkins host and port, JOB_TOKEN is the Jenkins job token.


Check the bitbucket webhook logs or history

In Bitbucket Cloud, edit the webhook and check Request History Enable request history collection. This enables logging of the request sent to Jenkins, and the response received from Jenkins.

If you see a message like:

  "jobs": null,
  "message": "Did not find any jobs with GenericTrigger configured! If you are using a token, you need to pass it like ...trigger/invoke?token=TOKENHERE. If you are not using a token, you need to authenticate like http://user:passsword@jenkins/generic-webhook... "

you have to configure a Jenkins user and auth token in the URL.

Check received parameters

In Jenkins job configuration, check

  • Print post content: Print post content in job log.
  • Print contributed variables: Print contributed variables in job log.

    Print post content