This page last changed on May 08, 2007 by rosie@atlassian.com.

Bamboo Plugins Overview

A Bamboo plugin is a single JAR containing code, a plugin descriptor (XML) and usually some Freemarker template files to render HTML.

The plugin descriptor is the only mandatory part of the plugin. It must be called atlassian-plugin.xml and be located in the root of your JAR file.

Each plugin consists of one or more plugin modules. These are of different types (for example a report, or a post-build action) and each has an individual XML element describing it. Each module is described below together with the XML element required for it.

Here is a sample of the descriptor with highlighted elements:

<!-- the plugin key must be unique, think of it as the 'package' of the plugin -->
<atlassian-plugin key="com.atlassian.plugin.sample" name="Sample Plugin">
    <!-- a short block describing the plugin itself -->
    <plugin-info>
        <description>This is a brief textual description of the plugin</description>
        <!-- the version of the plugin -->
        <version>1.1</version>
        <!-- the versions of the application this plugin is for -->
        <application-version min="3.0" max="3.0"/>
        <!-- details of the plugin vendor -->
        <vendor name="Atlassian Software Systems Pty Ltd" url="http://www.atlassian.com"/>
    </plugin-info>

    . . . 1 or more plugin modules . . .
</atlassian-plugin>

Each plugin has a plugin key which is unique among all plugins (eg "com.atlassian.plugin.sample"). Semantically this equates to the package of a Java class. Each module within the plugin also has a module key which is unique within the plugin (eg "myreport"). Semantically this equates to the class name of a Java class.

The plugin key + module key are combined to make the complete key of the plugin module (combining the examples above, the complete key would be "com.atlassian.plugin.sample:myreport"). Note: a : is used to separate the plugin key from the module key.

Setting up a Bamboo Plugin Project

Refer to the Getting Started guide.

Deploy a Bamboo Plugin

Installing plugins in Bamboo is easy.

Once you have downloaded or created your plugin jar, follow these steps:

  1. Shut down Bamboo
  2. copy '$MY_COOL_PLUGIN.jar' into '.../webapp/WEB-INF/lib/'
  3. Start up Bamboo. Your plugin should be automatically installed and activated.
  4. Enjoy!

Bamboo Plugin Module Types

The following types of plugin modules are supported by Bamboo

Module Type Since version... Documentation Description
builder 1.0 Builder Plugin Module Add new builders to Bamboo
xwork 1.0 XWork Plugin Module XWork actions and views bundled with the plugin. This enables building generic user interfaces.
report 1.0 Report Module Defines a report of build telemetry data.
preBuildAction 1.1 Pre Build Action Module Prepends a custom synchronous process to the build. Occurs before the builder has run.
buildProcessor 1.0 Build Processor Module Append a custom synchronous process to the build. Occurs after the builder has run.
buildCompleteAction 1.0 Build Complete Action Module Add a custom asynchronous action after the build process has completed.
postBuildIndexWriter 1.0 Post Build Index Writer Module Writes custom build data into the index for report generation.
indexReader 1.0 Index Reader Module Reads out custom index information written by the postBuildIndexWriter from the index.
web-item 1.0 Web Item Module Add new links to the Bamboo interface
web-section 1.0 Web Section Module Add a new section to the Bamboo interface
web-resource 1.0 Web Resource Module Add a new resource to the Bamboo application (e.g. javascript)
notificationCondition 1.1 Notification Condition Module Add new notification condition

Built-in Bamboo system plugins

A number of functions and areas within Bamboo are shipped as built in plugins. These can also be useful for plugin developers who want to know more about how to create their own plugins, as they showcase the functionality that can be built.

The system plugins are referenced from the following files (located in /WEB-INF/classes:

  • system-builder-plugin.xml - the built in builders, including Ant, Maven, and Maven 2.
  • system-clover-plugin.xml - the built in Clover analytics.
  • system-jira-plugin.xml - the built in tab view of JIRA issues in a build.
  • system-labelling-plugin.xml - the built in automatic build labeller.
  • system-reports-plugin.xml - the built reports of builds grouped by time periods under the Reports tab.
  • system-webUI-plugin.xml - the built in menu items under the Administration tab as well as the tab menu items on the View Plan page and the View Build Results page.
  • system-notifications-plugin.xml - the build in notification conditions, including all builds, failed builds, after X failed builds. 
RELATED TOPICS





Bamboo Documentation Home

Document generated by Confluence on May 08, 2007 23:47