Bamboo API 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

• New plugin points
• Changes in behavior
• Compatibility layer
• Automatic conversions and migration
• Deprecations and replacements

vcsType

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

Example

1
2
<vcsType key="gitv2" name="Git" class="com.atlassian.bamboo.plugins.git.v2.GitWorkingCopyManager">
  <description>A Git repository</description>
  <uniqueRevisionIds>true</uniqueRevisionIds>
  <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"/>
</vcsType>

repository2VcsTypeConverter

Provides conversion of the configuration between repository and vcsType plugins.

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

vcsRepositoryViewer

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

1
2
<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"/>
  <supportedVcs>
    <vcsType>com.atlassian.bamboo.plugins.stash.atlassian-bamboo-plugin-stash:bbserver</vcsType>
  </supportedVcs>
</vcsRepositoryViewer>

web2VcsRepositoryViewerConverter 

Provides conversion of the configuration between webRepositoryViewer and vcsRepositoryViewer plugins.

1
2
<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:

1
2
c.a.b.repository.RepositoryDefinitionManager.getPlansUsingRepository
c.a.b.repository.RepositoryDefinitionManager.getIdentifiersOfPlansUsingRepository

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:

1
2
c.a.b.repository.RepositoryDefinitionManager.getIdentifiersOfPlansUsingRepositoryOrItsDirectChildren

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