Brigade Bitbucket Gateway

The Brigade Bitbucket Gateway receives events (webhooks) from Bitbucket, transforms them into Brigade events, and emits them into Brigade's event bus.

⚠️ If you are familiar with the Brigade GitHub Gateway, be advised that this gateway is not as full-featured as that one. At this time, it merely offers parity with its predecessor -- the Brigade v1.x-compatible Bitbucket Gateway -- meaning it only handles simple webhooks and does not offer any integration with Bitbucket Cloud Apps.

A more full-featured successor to this gateway is something the Brigade maintainers do wish to explore in collaboration with the Brigade community. Please reach out on the Kubernetes/#brigade Slack channel if you are interested in working on that.

Creating Webhooks

After installation, browse to any of your Bitbucket repositories for which you'd like to send webhooks to this gateway. From the menu on the left, select Repository settings and then Webhooks. On this page, click Add webhooks.

In the Title field, add a name for your webhook. It must be unique to this repository.
In the URL field, use a value of the form https://<DNS hostname or publicIP>/events. Note that Bitbucket will not permit URLs that it cannot reach.

⚠️ Instructions for finding the public IP are in the installation docs.
Check the Active checkbox.
If you're using a self-signed certificate (again, refer to the installation docs), check the Skip certificate verification checkbox.
Check any/all triggers for which you'd like a webhook sent to this gateway.
Click Save

⚠️ Those who are also familiar with the Brigade GitHub Gateway might be perplexed at the lack of anything along the lines of a "shared secret" when configuring webhooks in Bitbucket. How then do webhook requests authenticate themselves to your gateway? In short, they do not. In practice, however, this does not mean that just anyone can send webhooks (directly) to your gateway.

This gateway is pre-configured (see Helm chart configuration options) with a list of allowed IPs / IP ranges for inbound requests. This list reflects the IPs utilized by Bitbucket for outbound requests. This effectively prevents anyone except Bitbucket from (successfully) sending webhooks to your gateway.

This strategy does not, however, prevent any random Bitbucket user (who happens to know the address of your gateway) from configuring their own repositories to send webhooks your way. However, this matters very little, because Brigade 2 operates on a subscription model and if none of your own Brigade projects subscribe to events originating from the third-party repository in question, nothing happens.

Subscribing

Now subscribe any number of Brigade projects to events emitted by this gateway -- all of which have a value of brigade.sh/bitbucket in their source field. You can subscribe to all event types emitted by the gateway, or just specific ones.

In the example project definition below, we subscribe to issue:created events, provided they've originated from the fictitious example-org/example repository (see the repo qualifier). You should adjust this value to match a repository for which you are sending webhooks to your new gateway (see installation instructions).

apiVersion: brigade.sh/v2
kind: Project
metadata:
  id: bitbucket-demo
description: A project that demonstrates integration with Bitbucket
spec:
  eventSubscriptions:
  - source: brigade.sh/bitbucket
    types:
    - repo:push
    qualifiers:
      repo: example-org/example
  workerTemplate:
    defaultConfigFiles:
      brigade.js: |-
        const { events } = require("@brigadecore/brigadier");

        events.on("brigade.sh/bitbucket", "repo:push", () => {
          console.log("Someone pushed a commit to the example-org/example repository!");
        });

        events.process();

Assuming this file were named project.yaml, you can create the project like so:

$ brig project create --file project.yaml

Creating a new issue in the corresponding repo should now send a webhook from Bitbucket to your gateway. The gateway, in turn, will emit an event into Brigade's event bus. Brigade should initialize a worker (containerized event handler) for every project that has subscribed to the event, and the worker should execute the brigade.js script that was embedded in the project definition.

List the events for the bitbucket-demo project to confirm this:

$ brig event list --project bitbucket-demo

Full coverage of brig commands is beyond the scope of this documentation, but at this point, additional brig commands can be applied to monitor the event's status and view logs produced in the course of handling the event.

Contributing

The Brigade project accepts contributions via GitHub pull requests. The Contributing document outlines the process to help get your contribution accepted.

Support & Feedback

We have a slack channel! Kubernetes/#brigade Feel free to join for any support questions or feedback, we are happy to help. To report an issue or to request a feature open an issue here

Code of Conduct

Participation in the Brigade project is governed by the CNCF Code of Conduct.

brigadecore / brigade-bitbucket-gateway

readme