Bitbucket Post Webhook sends data to external systems like Jenkins, Azure DevOps and other systems that should be triggered from outside.

Basic information

Bitbucket Post Webhooks makes it possible to post JSON data to an HTTP/HTTPS address. The data is sent when a configured event occurs and all filters are passed.

Jenkins 2.0 plugin is supported. Azure DevOps Pipelines (Server and Cloud) triggering is supported as well.

More information how to setup Jenkins.

Main features

  • You can send JSON payload from Bitbucket Server or Data Center to an external system like Jenkins, customer scripts, Serverless functions, etc

  • You can configure the rules on a global, project and repository level. Corresponding permissions are respected.

  • You can configure the HTTP method: POST (default), PUT and GET(not HTTP body sent).

  • Support of Basic authentication.

  • Support of Azure DevOps Pipelines (Cloud and Server).

  • You can filter events by:

    • Event (including Repository Mirror Synchronised, Build Status Update and other events)

    • Committers

    • Branch masks

      • Branches to ignore (a list of masks)

      • Branches to consider (a list of masks)

      • Possibility to filter by from/to branches (valid for pull request related events)

    • Project

  • You can use API to create rules. The same APIs are use by Bitbucket Branch Source Jenkins plugin.

  • You can skip SSL, url validations.

  • If something is missing please reach out.

Frequently Asked Questions

You can find Bitbucket Post Webhook Frequently Asked Questions here.

Configuration

Repository configuration

Important: repository configuration by default overrides project and global configuration (this is configurable in the latest versions).

In order to setup webhook posts you need to select the events and filters about which you want to notify your system about. It can be Jenkins branch source plugin or any other system.

The configuration is available at Repository → Settings → Post Webhooks.

When you start with an empty list you need to add a new configuration.

You need to click “Add webhook“. Here is picture how it looks (July 2020).

Here you need to setup:

  • the title - what is the name of the configuration (can be something random, or meaningful with your repo or person name). Our advice is to name something meaningful to you and your team so that it can be understood later easier.

  • Override project and global settings. On by default. You can use this setting to override project and global setup. If it is off, the project and global level configuration will take precedence.

  • the URL - where the data should be sent to. F.e.

    • You can skip SSL verification and test connection with additional auxiliary settings.

    • {project.key} variable can be used as part of the url to be replaced by Bitbucket project’s key.

    • {repository.slug} variable can be used as part of the url to be replaced by Bitbucket repository’s slug.

    • You can change the HTTP method to be used. Note: for GET the HTTP body is NOT sent.

  • You can configure basic authentication and Azure DevOps Pipelines token.

  • Committers to ignore (full match) - the comma-separated list of Bitbucket user names that should not trigger an event. Important: not display names, but usernames. This often used to ignore pushes from you continuous integration user. For instance, you could put there jenkins-user.

  • Branches to consider (regex) - the comma-separated list of Bitbucket branch regular expressions that should be considered when filtering events. For instance, release/*, tag/*, etc.

  • Branches to ignore (regex) - the comma-separated list of Bitbucket branch regexes that should be ignored. For instance, release/*, tag/*, etc.

  • Branches To or From. Which branches should be looked at for Branches to consider or ignore.

  • Active - should be On if this configuration to be used.

  • Select the list of the events that you want to notify your external system about.

  • Skip CI - a setting which allows to skip notification for the pull requests if [ci skip] or [skip ci] is present in the pull request’s title or description.

For instance, you don’t want to notify Jenkins about the changes made by Jenkins user to not trigger cyclomatic build dependency, so you will add the Jenkins user to the committers to ignore.

Project configuration

Important: project level configuration by default overrides global configuration.

The configuration screen is available for project and global admins at Project settings → Workflow → Post Webhooks.

At the project level you can also see all repository rules.

The setup process is the same as for the repository rules (please see above). Do remember that you can use string substitutes for project’s key and repository’s slug.

Global configuration

The global configuration screen for global admins at Administration → Add-ons → Post Webhooks.

At the global level you can also see all repository and project level rules.

The setup process is the same as for the repository rules (please see above). Do remember that you can use string substitutes for project’s key and repository’s slug.

Enable multiple rules on the repository level

This setting is located in the Global settings → Multiple configuration checkbox.

Build status event handling

Bitbucket build status API provides only commitId and Bitbucket Post Webhooks needs to find rules to process an event. Because App cannot get repository information it uses two approaches to find repository by commit id:

  • Default (since 3.12.23): we cache commit id and repository id, so that we can find repository id by commit id in O(1) time.

  • Repository search (default before 3.12.23): Apps scans all repositories, projects, globally where rules exist with Build status notification enabled. This approach is not very performant when a repository is huge, because it results in a a repository scan. This approach is disabled by default since version 3.12.23. You can enable it in the global setting (“Enable repositories scan to find commit for build status“ checkbox).

Trigger Azure DevOps Pipelines Cloud and Server (On-Premises)

You can use Bitbucket Post Webhook App to trigger Azure DevOps Pipelines.

You need to generate an API token that allows to execute required action. https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=preview-page#create-a-pat

It should allow to trigger the build pipelines, nothing more. No code access is required.

Please set the url in the provided field.

Azure DevOps Pipeline trigger by Post Webhooks for Bitbucket

And specify the url to the pipeline in the following format:

Cloud: The url should match the following pattern https://dev.azure.com/{ORG_NAME}/{PROJECT_NAME}/_build?definitionId={PIPELINE_ID}

Server: The url should match the following pattern https://yoursever/{COLLECTION}/{PROJECT_NAME}/_build?definitionId={DEFINITION_ID}

Dealing with removed/moved repositories

In the latest versions (3.12+) App updates/deactivates configurations when a repository or a project renamed or moved. Which highlights the rules which may need a fix.

In the older versions, you may see RepositoryMovedException. Follow the document below to delete/change older issues. However, the best approach is to update to the latest version and fix the highlighted rule in the Global configuration.

Bitbucket RepositoryMovedException

API

Please navigate to the API documentation - Atlassian Bitbucket Post Webhook API.

Outgoing API contracts are here - Post Webhooks for Bitbucket outgoing API

Providing feedback

Please contact us via the Service Desk.

Debugging

You need to enable debug mode for Bitbucket and supply us with the support zip or Bitbucket log file.

Last updated: