extrawurst's blog

Developing Atlassian Bitbucket plugins

• general

At work we are using bitbucket server for our source code and slack for our communication. The following gives you an insight into how to make a bitbucket plugin that talks to Slack.


The Why

My team at InnoGames is responsible for a long list of repositories and is heavily utilizing pull-requests to do code-review.

PRs were lying around a lot unless authors pro-actively asked for reviews. So we wanted to automate this better and found a bitbucket plugin that forwards pull-request reviews to slack: Stash2Slack (see in Marketplace).

Unfortunately Stash2Slack turned out not to have a rest api to have its settings configured which is a requirement for us since we have automation of settings configuration on our multitude of repositories (we checked the source code on github).

I decided to add this feature to the plugin and this post is a summary on steps necessary to develop a bitbucket plugin that I wish I had when I started.

The following is a short recap of the (sometimes) not so obvious steps to take to work on an Atlassian Bitbucket plugin.

The Setup (on mac)

Three simple steps to get up and running:

Install Prerequisites (see Atlassian Docs)

Run local BB server

Run your plugin

The actual change

Now the actual change was pretty simple:

See the manifest changes here:

<rest key="slack-rest" path="/stash2slack" version="1.0">
    <description>Stash2Slack Rest API</description>

See an example REST endpoint here:

public class RestResource {

    public Response getGlobalSettings() {
        validate(() -> validationService.validateForGlobal(Permission.ADMIN));

        return Response.ok(getDTOFromGlobalSettings(globalSettingsService)).build();

Find the entire changeset here on github.


This was obviously just a quick overview but working with atlassian plugins seems fun and I found a couple of possible improvements I would like to tackle.

Debug local instance

For my testing so far I did not need to connect via debugger right into my plugin but I can see how knowing how is beneficial.

So here is an explanation on how to run your local instance to be able to debug it (on port 8000): Run in debug mode

And here you find how to configure your IntelliJ to be able to connect to it: Setup IntelliJ

Thread support to improve readability

For now the plugin dumps all updates into a single slack channel sequentially. As said we handle a lot of repositories and one thing I would like to integrate is thread support for those messages to have a cleaner overview (one thread per PR).

Unfortunately this is not that easy so it ended up in the backlog: The simple webhooks for sending slack messages does not support threading so this idea was a deadend unless I want to invest into a bigger more sophisticated implementation.

Although I see a lot of opportunities to cleanup the current code that creates the webrequests manually when switching to jslack (a very nice java client lib for communicating with slack)

Server State and Active objects

Another problem I came across is the flawed way settings are saved. This manifests in this plugin being very error prone when used in a bitbucket server setup with multiple nodes.

It uses PluginSettings to store settings which are not synchronized between nodes and it should use ActiveObjects which is even stated in this forum thread: here - too bad the docs for atlassian plugin development are rather lacking.

Repo is dormant

My addition to the plugin in shape of a PR is completely ignored now, no wonder since the repo was not updated in a year. The author clearly moved on. I would like to dig into how to distribute an Atlassian plugin to maybe supply this updated version to a broader audience. If only I had time…

comments powered by Disqus