Soy API

Bitbucket Server exposes a Soy (Closure Templates) API that you can use to add widgets to your pages.

Currently the Bitbucket team only supports a single template as API. That component is the bitbucket.component.branchSelector.field template and is primarily meant for use in Repository Hook configuration forms. No Web Resource dependency is required to use it from a configuration form, however if it is to be used elsewhere you must depend on the appropriate web resource module. See the template documentation for more details.

Compatibility Policy

The Soy API's compatibility policy matches that of Bitbucket's other APIs. Soy APIs will not contain breaking changes between minor versions (e.g. 4.0 and 4.1). Instead, any removed or modified templates and parameters will have a 'deprecated' CSS class added to their output HTML when used, and the legacy behavior will cease to work in the next major release (e.g. Bitbucket Server 5.0).

"Breaking changes" describes removal of templates or template parameters, or changes to accepted template parameter values that would cause previously valid input to generate invalid HTML, or throw an error. Behavior for invalid inputs may change at any release, and mutation of Soy templates is not supported. See API Scope for details.

Loading the APIs

Soy APIs are not guaranteed to be available on the page. Before using an API you MUST depend on the matching web-resource module for that API. Look at the documentation for a template to determine the dependency required. See the Web Resource Plugin Module documentation for details about how they work.

API Scope

Templates

The scope of the Soy API is limited to the Soy namespaces of bitbucket.component.* and aui.*. The stability of any other Soy templates is not guaranteed between minor versions.

For any template under that namespace, we guarantee that the template will continue to exist across minor versions. New templates may also be added between minor versions.

Parameters

If a template parameter is listed as optional it is not required and won't become a required parameter between versions.

If a parameter name ends in Content, then it expects valid, pre-escaped HTML strings as the value. You should not pass raw strings into these parameters, especially if they come from user input, as this would create a security vulnerability in Bitbucket.

Explicitly out of scope

The markup generated by the Bitbucket templates is explicitly undefined and unstable. You MUST NOT rely on the shape of that markup, except through CSS classes and IDs you have explicitly defined through the extraClasses and id parameters to the template.

The version of Closure Templates used in Bitbucket MAY change. We will make a best-effort attempt not to introduce breaking changes through upgrades to Closure Templates.