Bitdock

Intermediate service to handle Bitbucket ‘pull-request’ notifications and push them into Flowdock

Installation

Installation is simple with pip:

$ pip install bitdock

Building from source

You can also build manually from the source for more control. First obtain a copy of the source by either downloading the zipball or cloning the public repository:

git clone git@bitbucket.org:ftrack/bitdock.git

Then you can build and install the package into your current Python site-packages folder:

python setup.py install

Alternatively, just build locally and manage yourself:

python setup.py build

Building documentation from source

To build the documentation from source:

python setup.py build_sphinx

Then view in your browser:

file:///path/to/bitdock/build/doc/html/index.html

Dependencies

Additional For testing

Usage

Once installed you need to grab a relevant API token from Flowdock. Go to https://www.flowdock.com/account/tokens and copy an appropriate token (for example, a token for a flow called ‘Dev’):

_images/flowdock_api_token.png

Then start the Bitdock service from the command line passing your copied API token as the sole parameter:

python -m bitdock [YOUR_FLOWDOCK_API_KEY]

Note

To see additional runtime options (such as setting host and port interface) use:

python -m bitdock --help

Now the server is up and running it is time to head over to the Bitbucket project you want to receive notifications for. Once there, navigate to the Settings ‣ Hooks page and add a new Pull Request POST hook.

Check only the Create / Edit / Merge / Decline option and then enter the full public URL to your running server adding ‘/bitbucket-pull-request’ at the end. For example:

http://example.com:9000/bitbucket-pull-request
_images/bitbucket_add_hook.png

Click Save.

Now whenever a Bitbucket pull request is created or updated you should see a new entry in your Flowdock inbox for the configured flow.

_images/flowdock_inbox.png

Note

Assigned reviewers will show up as people tags on the inbox entry.

Mapping Users

As folks may have different user details on Bitbucket and Flowdock there is a basic way to map from one to the other. Start the server passing in a path to a JSON file containing mappings or Bitbucket usernames to Flowdock user details. For example:

my_mappings.json

{
    "martin": {
        "username": "mphillips",
        "display_name": "Martin Pengelly-Phillips",
        "email": "martin@example.com"
    },
    ...
}

Run the server using:

python -m bitdock --user-mapping my_mappings.json

API reference

bitdock

class bitdock.__main__.Bitdock(flowdock_api_key, user_mapping=None)

Bases: object

Bitdock main handler.

__init__(flowdock_api_key, user_mapping=None)

Initialise handler with flowdock_api_key.

In addition, optionally specify a user_mapping to use when mapping users. It should be a dictionary of Bitbucket user names against Flowdock user dictionaries. The Flowdock user dictionary should contain keys for username, display_name and email.

bitbucket_pull_request()

Handle bitbucket pull request notification.

flowdock_api_url

Return flowdock api url.

bitdock.__main__.main(arguments=None)

Bitdock: Connect Bitbucket and Flowdock.

Glossary

Indices and tables