Changes for 5.14

New repository API

In Bamboo 5.14 we've reimplemented the repository subsystem. While plugins that are using the old system are still supported through the compatibility layer, we strongly encourage plugin developers to migrate to the new API.

Key concepts

The new API has been designed according to the following guidelines:

  • separation of concerns: the classes that execute actual operations and need to run on agents must be separate from agents that handle the configuration and are only run server-side
  • the implementation should be stateless
  • plugin submodules are preferred over optional interfaces for clarity
  • functionality can be split into multiple runtime classes
  • configuration needs to be split by functionality and scope to allow selective inheritance and data overrides

New plugin points


The implementation of the VCS repository support. Replaces the repository plugin point. The minimum implementation must provide:

  • the main module (implementation of com.atlassian.bamboo.vcs.runtime.VcsWorkingCopyManager)
  • serverConfigurator module (implementation of com.atlassian.bamboo.vcs.configurator.VcsLocationConfigurator)
  • changeDetector module (implementation of com.atlassian.bamboo.vcs.runtime.VcsChangeDetector)
  • viewServer and editServer templates for the UI


<vcsType key="gitv2" name="Git" class="com.atlassian.bamboo.plugins.git.v2.GitWorkingCopyManager">
  <description>A Git repository</description>
  <serverConfigurator class="com.atlassian.bamboo.plugins.git.v2.configurator.GitServerConfigurator"/>
  <branchConfigurator class="com.atlassian.bamboo.plugins.git.v2.configurator.GitBranchConfigurator"/>
  <changeDetectionConfigurator class="com.atlassian.bamboo.vcs.configuration.configurator.DefaultChangeDetectionOptionsConfigurator"/>
  <changeDetector class="com.atlassian.bamboo.plugins.git.v2.GitChangeDetector"/>
  <branchDetector class="com.atlassian.bamboo.plugins.git.v2.GitBranchDetector"/>
  <connectionTester class="com.atlassian.bamboo.plugins.git.v2.GitConnectionTester"/>
  <variableGenerator class="com.atlassian.bamboo.plugins.git.v2.GitVariableGenerator"/>
  <mavenPomAccessor class="com.atlassian.bamboo.plugins.git.v2.configurator.GitMavenPomAccessor"/>
  <exporter class="com.atlassian.bamboo.plugins.git.v2.exporter.GitConfigurationExporter"/>

  <resource type="freemarker" name="editServer" location="/com/atlassian/bamboo/plugins/git/v2/gitServerEdit.ftl"/>
  <resource type="freemarker" name="viewServer" location="/com/atlassian/bamboo/plugins/git/v2/gitServerView.ftl"/>
  <resource type="freemarker" name="editBranch" location="/com/atlassian/bamboo/plugins/git/v2/gitBranchEdit.ftl"/>
  <resource type="freemarker" name="viewBranch" location="/com/atlassian/bamboo/plugins/git/v2/gitBranchView.ftl"/>
  <resource type="freemarker" name="editAdvancedServerOptions" location="/com/atlassian/bamboo/plugins/git/v2/gitEditAdvancedServerOptions.ftl"/>
  <resource type="freemarker" name="viewAdvancedServerOptions" location="/com/atlassian/bamboo/plugins/git/v2/gitViewAdvancedServerOptions.ftl"/>
  <resource type="freemarker" name="branchIntegrationEdit" location="/com/atlassian/bamboo/plugins/git/v2/branchIntegrationEdit.ftl"/>


Provides conversion of the configuration between repository and vcsType plugins.

<repository2VcsTypeConverter key="gitConverter" name="Git converter" class="com.atlassian.bamboo.plugins.git.v2.converter.GitConfigurationConverter"/>


The implementation of the web repository viewer. Replaces the webRepositoryViewer plugin point.

<vcsRepositoryViewer key="bbServerViewer" name="Bitbucket Server" class="com.atlassian.bamboo.plugins.stash.v2.viewer.BitbucketServerVcsRepositoryViewer">
  <description>Renders Bitbucket Server links for commits.</description>
  <configurator class="com.atlassian.bamboo.plugins.stash.v2.viewer.BitbucketServerVcsRepositoryViewerConfigurator"/>


Provides conversion of the configuration between webRepositoryViewer and vcsRepositoryViewer plugins.

<web2VcsRepositoryViewerConverter key="viewerConverter" class="com.atlassian.bamboo.plugins.stash.v2.converter.BitbucketServerVcsViewerConverter"/>

Changes in behavior

We've introduced the parent - child relationship between RepositoryDataEntity objects. With Bamboo 5.14, the data can be inherited from a parent repository, which allows to solve a problem when changes to a global or plan repository are not propagated to plan branches.

Linked (global) repositories are not longer directly attached to plans (by PlanRepositoryLink). Instead, a child inheriting from a linked repository is created and attached to a plan by PlanRepositoryLink object.

As a consequence, the behavior of the following methods has changed:


The methods will return empty collections when invoked with global repository ID as a parameter.

In order to fetch plans that use a linked repository, the inheritance relationship needs to be checked by calling:


Compatibility layer

Classes implementing the repository plugin point are wrapped by the compatibility layer, which allows them to be used as if they implemented the new interface. However, the functionality that relies on the configuration being split into parts is not supported for those repositories.

Classes implementing vcsRepositoryViewer are wrapped by the compatibility layer, but due to major difference in the design, it can't be guaranteed that they will work correctly in Bamboo 5.14.

Code that accesses repositories through the old API, in particular tasks plugins, is partially supported. Whether it works or not depends on the repository:

  • old repository plugins are fully supported in that context
  • a new implementation will work if it is convertible to the old-style plugins

Code that manipulates configuration of repositories using the old API is partially supported. Old-style repositories are automatically converted to the new style on save, if an applicable converter exists. For example, if some client code tries to save configuration of an old git plugin, the configuration is converted to gitv2 plugin, and that is saved to the database. Code that relies on the changed behavior (see above) will not work correctly in Bamboo 5.14.

Automatic conversions and migration

When implementing vcsType or vcsRepositoryViewer, a corresponding converter can be provided. This allows Bamboo to automatically convert configuration of the repository that was implemented in the old API. The conversion is invoked:

  • when Bamboo is restarted
  • when save is invoked with an old-style repository configuration
  • when a new-style repository is used through the old API the reverse conversion is executed

All repositories provided by Bamboo that are implemented in the new system provide conversion in both directions.

Deprecations and replacements





and its subclasses

c.a.b.vcs.configurator.VcsLocationConfigurator, c.a.b.vcs.configurator.VcsBranchConfigurator,...
c.a.b.vcs.runtime.VcsWorkingCopyManager, c.a.b.runtime.VcsChangeDetector,....

The functionality of this class has been split into number of interfaces handling different functionalities.

Configuration is now handled separately from runtime. Configuration can now be split into parts that are handled and can be inherited independently.

Runtime implementation is now stateless. A separate interfaces are provided for different operations like change detection, checking out, merges, branch detection.



The new manager gives access to the old-style plugins wrapped by the compatibility layer.






PartialVcsRepositoryData should be used for CRUD.

VcsRepositoryData and PlanRepositoryData should be used for run time (for example, in tasks).
Old methods will use compatibility layer and reverse conversion to produce data in the old format. Note that the reverse conversion might be not available.
c.a.b.repository.RepositoryConfigurationService c.a.b.vcs.configuration.service.VcsRepositoryConfigurationService

Old implementation forwards calls to the new service.

Conversion from an old to a new plugin is invoked on save when applicable.




Configuration handling is now separate from runtime. Implementations should be stateless.



The new manager will gives access to the old-style plugins wrapped by the compatibility layer.

Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport