Service Integration
Introduction
Bitbucket offers integration with external services by allowing a set of services, or brokers to run at certain events.
These brokers are simple Python scripts, that receive information about the event and upon receiving those, they will take action. For example, there's a broker for sending emails, and one for POSTing back to an arbitrary URL.
We also allow you to write your own. More on that later.
How to use brokers
Brokers are enabled on a per-repository bases, by the repository administrator. From the repository administration page, there is a link to the service integration configuration.
On the page, you will see a dropdown of services available. You may add as many as you want, and even more of the same type. There's no reason why you shouldn't be able to email several people, or even ping several separate URLs.
Once you've configured the service, it will be active.
When does the service run?
A service will run once we have received data from you. Because of the decentralized nature of Mercurial et. al, you can commit something locally, without notifying us. It's not until you push your changesets to us, that you're actually connecting to us, and uploading data.
Because of this, a service may receive more than one changeset, and some of the services take this into consideration. For example, the email broker will construct two different emails to send, based on the number of changesets. If there is more than one, it will have a summary as the subject, and an aggregate as the body.
Writing your own brokers
Because you may have special cases, or you may need a broker that we haven't yet provided you with, we are opening up the very same API as we use for writing the brokers, to you. This will allow you to easily write a broker, and submit it to us for verification. Once verified, we can put it into production, and you can start using it.
Due to the technical nature of this document, it is located at its own page, here.