Jenkins Bitbucket Integration

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 Configure → Build 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 $.pullrequest.destination.branch.name 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 Configure → Build 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.

Troubleshooting

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

Links

• Manage webhooks from the Bitbucket Support wiki.
• Jenkins plugin generic-webhook-trigger