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.
Activating a service
Services can be activated on a per-repository basis by the administrator. Go to your repository page, select the Admin tab, click Services, then select a service from the list, and add it.
Currently provided services
POST
You specify a url, and Bitbucket will post info to it when your project is updated. You can think of this as an HTTP publish/subscribe service.
Send info to Twitter.
The default format is:
${repository.name} - ${commit.author} - ${commit.message}
You can change the template to suit your own needs.
There's also a shortcut for creating a TinyURL to the commit: ${commit.tinyurl}
FriendFeed
This service will send your commit info to FriendFeed as a feed. You need to enter your remote key to use this service and you can find yours in here: friendfeed.com/remotekey
The default format is:
${repository.name} - ${commit.author}
You can change the template to suit your own needs just like in Twitter service. The commit message will be feed's first comment on FriendFeed.
You can use TinyURL shortcut in order to display your repository link shorter, but FriendFeed trims links by default anyway.
Fogbugz
With this service, you can integrate Bitbucket with Fogbugz, an issue-tracking and project-management system.
Basecamp
With this service, you can integrate Bitbucket with Basecamp, a web-based project management application.
Lighthouse
With this service, you can integrate Bitbucket with Lighthouse, a simple issue tracking system.
Check Lighthouse Integration for more information.
CIA.vc
CIA.vc is an online service which collects change information from version control systems around the world. These changes are broadcast in real-time to the web site and to Internet Relay Chat.
The primary CIA.vc installation lives at http://cia.vc/
Issues
The issues service scans commit messages for commands which will automatically change the state of the relevant issue on the tracker.
To link your commit to an issue, include somewhere in your commit message the following fragment:
<command> <issue id>
where the <command> can be any of the following:
close/closed/closes//closing/fix/fixed/fixes # resolves the issue reopen/reopens/reopening # reopens the issue addresses/re/references/ref/refs/see # adds a link to the changeset as a comment for the issue
For an example issue 4711, the <issue id> can be of the following form:
#4711
issue 4711
bug 4711
ticket 4711
Examples:
"... fixes #4711 ..." # marks issue as resolved "... reopening bug 4711..." # marks issue as open "... refs ticket 4711..." # links changeset to issue as comment "... refs bug #4711 and #4712..." # links to multiple issues
Note: When displayed in the changeset view, #4711 will link back to the issue, while issue 4711 will not.
The email service sends an email for each pushed changegroup.
Emails are sent from commits-noreply@bitbucket.org.
When a changegroup only contains one changeset, the mail subject will be of the form:
Subject: commit/<project>: <user>: <commit msg>
When a changegroup contains two or more changeset, the email subject will be of the form:
Subject: commit/<project>: <x> new changesets
Email Diff
The email service sends an email with diffs.