Configuring plugin settings

Hello! I’ve been working on developing my BB first plugin which is a RepositoryMergeCheck. The idea is to gate merging on required builds with some exceptions and the ability to override with a comment, enable for only some branches, etc. I’ve gotten to the point where I need to have a configuration UI so that repo admins can control which builds are required, etc.

After looking at the documentation (or lack thereof) I am completely lost. All I have figured out right now is the modern way seems to be using Soy templates.

Questions about Soy:
The templates in the AUI repo are kinda helpful but there is no visibility into what objects you are talking to when you specify @param <param name> in the comments. How do I know what is in $config or where that gets set?

How can I dynamically provide content in the config UI? The UI will essentially consist of two pieces:

  1. the existing required builds
  2. A simple form to add a new required build.

AUI looks like it has a “RESTful table” but…there doesn’t seem to be templates for that in Soy…can I get around this?

Questions about the SDK:
I see forum posts saying to use PluginSettingsFactory to set repo level settings. Great! Looks like I can use this to store all kinds of objects. I also see Settings and SettingsValidator…This seems to be invoked when you change plugin settings but can only deal in primitive types? I need to be able to create an array of required builds and values bundled into types that make sense for my object. Which thing do I use? Is there a PluginSettingsValidator? Doesn’t appear to be but that sounds like what I need.

Overall this has just been an extremely frustrating experience because I don’t know what I don’t know and the documentation that is out there does little to explain how the modern settings config UI is all wired up from beginning to end.

Hi @MatthewSanford, in regards to AUI, you can find documentation here

You should check what version of AUI is used by Bitbucket and select the correct AUI Docs version:

To get this information, you can also type AJS.version in the browser console.

Here is the additional link to the source code of AUI soy templates:
this is a link for version 8.8.3 of AUI but you can change the version with a dropdown:

I hope that helps a bit.

Unfortunately, that isn’t helpful. That site is full of broken links or links that go nowhere. If the latest guidance is to use Soy templates, there should at minimum be some examples about how to do that within the documentation site.

These 404:

Hi Matthew,

I feel with you brother :smile:
I do use the BBS developer documentation quite a lot Beginner guide to Bitbucket Server plugin development and for most parts it works.
You can add the config form soy template name in atlassian-plugin.xml. Correct me if I’m wrong @madamczak here - the guide may be missing how to include the transformed soy template as a web resource, or, is transformation and resource loading automagically built into repo-merge-check-hooks?

Finally here is an open source BBS app you can get some ideas from how to incorporate the web resource with soy transformer.


The Decorate the user profile page guide does mention how to load and use the soy templates. You can check the Render the Template section.

Bitbucket is using <client-resource> that doesn’t require adding an additional <transformation> tag for “.soy” and has support for i18n out-of-the-box.
However, you can check the Confluence guide that mentions how to use the <web-resource> with Soy and i18n if you prefer.