Bamboo Development : Using Version 1 Plugins

By default the Atlassian Plugin SDK generates Version 2 (OSGi) plugins. Unfortunately Bamboo currently doesn't support Version 2 (v2) plugins for Remote Agents, meaning that plugin modules running on Agents require the Plugin to be a of Version 1 (v1). The most notable example is the Source Repository Module - which most commonly is executed on Remote Agents to access the source repository.

Ensure to always test your plugin with Remote Agents to verify that there are no NoClassDefFound exceptions.

Building Version 1 plugin using Atlassian Plugins SDK

A v1 plugin is a plain old jar that is available on the Bamboo classpath. It should not contain any OSGi descriptors in it's Manifest.mf. The tricky part is to make sure all dependencies get bundled with your plugin - either as separate jar or bundled with your plugin.

How do I ensure that my plugin has the right version?

See the atlassian-plugin section in Configuring the Plugin Descriptor where the plugin version is declared.

Ensuring valid scope of dependencies

This also applies to v2 plugins, but is especially important for v1 plugins as they can pollute Bamboo's classpath with wrong versions of classes.

Mark Bamboo (core) dependencies as provided

It's important not to include any jars that already ship with your Bamboo server. 

1
2
<dependency>
    <groupId>com.atlassian.bamboo</groupId>
    <artifactId>atlassian-bamboo-api</artifactId>
    <version>${bamboo.version}</version>
    <!-- Don't bundle API classes -->
    <scope>provided</scope>
</dependency>

Exclude transitive dependencies that are provided by Bamboo

atlas-mvn dependency:tree is your friend here.

1
2
<dependency>
    <groupId>org.eclipse.jgit</groupId>
    <artifactId>org.eclipse.jgit</artifactId>
    <version>0.9.3</version>
    <exclusions>
        <exclusion>
            <!-- jsch is provided by Bamboo -->
            <groupId>com.jcraft</groupId>
            <artifactId>jsch</artifactId>
        </exclusion>
    </exclusions>
</dependency>

Configure the project to bundle dependencies with the plugin jar

By default atlas-package from Atlassian Plugins SDK bundles dependencies for a v2 plugin layout. The jars are copied to META-INF/lib in the plugin jar which is suitable for OSGi deployment. To make plugin v1 work the jars need to be repackaged with the plugin jar so they are visible to non-OSGi classloader.

1
2
<plugin>
     <groupId>com.atlassian.maven.plugins</groupId>
     <artifactId>maven-bamboo-plugin</artifactId>
     <version>3.2.3</version>
     <extensions>true</extensions>
     <configuration>
          <productVersion>${bamboo.version}</productVersion>
          <productDataVersion>${bamboo.data.version}</productDataVersion>
          <!-- Version 1 compatible layout -->
          <extractDependencies>true</extractDependencies>
     </configuration>
</plugin>

Precautions

V1 plugins are plain old jars on the Bamboo classpath. The main reasons to use them instead of v2 plugins are to:

  • make them available to remote agents,
  • provide classes to be used by the system or other v1 plugins.

There are a few issues that should be taken into account:

  • Duplicate classes. It's especially difficult when multiple 3rd party plugins bundle the same classes. Duplicate classes are reported during Bamboo startup in the atlassian-bamboo.log. This becomes a problem when different plugins provide different versions of the jars. When adding a potentially popular dependency consider jarjar instead of unpack.
  • As a special case of above, be careful not to override other plugin's (or core) classes.
  • Full server restart is needed to upgrade the plugin - no atlas-cli possible.

Rate this page: