Write brokers/services for Bitbucket Cloud
Deprecated
Creation of new service integrations has been deprecated in favor of Bitbucket Cloud's webhooks, Connect integration framework, and email notifications.
No longer accepting new brokers
We are no longer accepting new brokers. Please refer to the information below about using the POST service.
Bitbucket Cloud integrates with external services through a set of brokers that run in response to certain events. Brokers are Python scripts that receive information about an event and then take one or more actions. For example, there is a Bamboo broker for integrating with Bamboo. The Bitbucket team developed many of our brokers. Third-party vendors also developed several brokers.
Using the POST service to integrate your application with Bitbucket Cloud
Most third-party web applications have a public RESTAPI. For example, Jenkins has a one. Using a third-party API, you can pass parameters to the service using Bitbucket's POST service. Bitbucket's POST service passes a payload to your third-party web application through its API. Your third-party application is responsible for receiving and transforming the payload.
To add a POST service to the Bitbucket repository:
- Review the third-party REST API for the appropriate POST call.
For example, your URL can include a user token such as:http://myservice/broker?token=bfkbd - Navigate to your repository
settings. - Choose Services from the left-hand navigation.
The Services page displays. - Choose POST from the services dropdown.
- Press Add service.
- Enter the URL for your third-party service.
- Press Save.
The new POST service appears in the active Services list.
The next time a user pushes to your repository, the POST service fires and sends a payload of data to your service. The service should receive the payload and handle the data appropriately using our REST API. For example, the application could call back into Bitbucket for specific resources using OAuth or other information, if needed.
The payload sent to your service by the service
The push payload, is a uniform dictionary containing information on the repository, the commits, and the service-specific values.
Example
{
"canon_url": "https://bitbucket.org",
"commits": [
{
"author": "marcus",
"branch": "featureA",
"files": [
{
"file": "somefile.py",
"type": "modified"
}
],
"message": "Added some featureA things",
"node": "d14d26a93fd2",
"parents": [
"1b458191f31a"
],
"raw_author": "Marcus Bertrand <marcus@somedomain.com>",
"raw_node": "d14d26a93fd28d3166fa81c0cd3b6f339bb95bfe",
"revision": 3,
"size": -1,
"timestamp": "2012-05-30 06:07:03",
"utctimestamp": "2012-05-30 04:07:03+00:00"
}
],
"repository": {
"absolute_url": "/marcus/project-x/",
"fork": false,
"is_private": true,
"name": "Project X",
"owner": "marcus",
"scm": "hg",
"slug": "project-x",
"website": ""
},
"user": "marcus"
}{
"canon_url": "https://bitbucket.org",
"commits": [
{
"author": "marcus",
"branch": "master",
"files": [
{
"file": "somefile.py",
"type": "modified"
}
],
"message": "Added some more things to somefile.py\n",
"node": "620ade18607a",
"parents": [
"702c70160afc"
],
"raw_author": "Marcus Bertrand <marcus@somedomain.com>",
"raw_node": "620ade18607ac42d872b568bb92acaa9a28620e9",
"revision": null,
"size": -1,
"timestamp": "2012-05-30 05:58:56",
"utctimestamp": "2012-05-30 03:58:56+00:00"
}
],
"repository": {
"absolute_url": "/marcus/project-x/",
"fork": false,
"is_private": true,
"name": "Project X",
"owner": "marcus",
"scm": "git",
"slug": "project-x",
"website": "https://atlassian.com/"
},
"user": "marcus"
}