This documentation relates to an earlier version of Bamboo.
View

Unknown macro: {spacejump}

or visit the current documentation home.

Please keep in mind that customisations are beyond the scope of what's covered by Atlassian Support.

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.

How does the Bamboo plugin system work?

A Chain (what users see as a Plan in the UI) consists of one or more Stages and each Stage consists of one or more Jobs.  Before progressing to the next Stage, every Job in the previous Stage must have completed successfully.  There is no order to Jobs within a Stage so when a Stage is executed, all Jobs in that Stage are placed in the queue immediately.

All triggering strategies now work at the Chain level.  Chains do not take Job information into account when deciding whether to trigger.  If repository polling or repository trigger strategies are selected, only changes detected against the Chain's are used to determine if the build will be triggered. 

Below is a diagram which shows Bamboo's build process flow, as well as the available plugin modules you can build.

Build Process For Chain

Build Process Per Job

Further Notes

  1. Build is Triggered — Changes are detected via polling (against the Chain's repository configuration only), manual builds, etc.
  2. Preperation for Build — The Build Number is determined then ResultsSummary objects and BuildContexts are created for the Chain and every Job within the Chain. The build number information, latest revision keys and ResultSummaries are persisted to the database.
  3. Job Queued — The server decides which agents can execute the job and queues the job.
  4. Agent Picks Up Job — The capability context is set. The job is removed from queue. The agent begins looping through the build tasks.
  5. Retrieve Source — The agent runs the CheckoutUpdateForBuild task. The Repository#retrieveSourceCode is called. If the Repository is RepositoryEventAware the appropriate methods will be called. The agent checks if the repository has changed since the last build and clears the source directory if it has.
  6. Prepare Job — The agent runs the PrepareBuildTask. This begins streaming the logs back to the server. The agent also runs the CustomPreBuildAction plugin point.
  7. Executes the Job — Timer begins. The agent runs the Builder#executeBuild. The CommandDecorator plugin will be run against the command line just before execution. After the Builder has been run, all the CustomBuildProcessors are run. Timer is stopped.
  8. Process Job Result — The server runs CustomBuildProcessorServer, checks if the job has passed and saves and indexes the result. The server also fires off the BuildCompletedEvent and PostBuildCompletedEvent events, and executes any CustomPostBuildCompletedActions.
  9. On BuildCompletedEvent (performed by the server) — Notifications are sent in this phase.
The following types of plugin modules are supported by Bamboo:

Build Lifecycle Plugin Modules​

Module Type

Plugin Framework Version

Since Bamboo version...

関連ドキュメント

説明

buildAgentRequirementFilter

1.x, 2.x

2.2

Build Agent Requirement Filter Module​

Customises the list of Agents a plan can be built on.

buildCompleteAction

1.x, 2.x

1.0

Build Complete Action Module

Add a custom asynchronous action after the build process has completed.

builder

1.x

1.0

Builder Plugin Module

Add new builders to Bamboo.

buildProcessor

1.x

1.0

Build Processor Module

Append a custom synchronous process to the build. Occurs on the Agent (both local and remote) after the builder has run.

buildProcessorServer

1.x

2.0

Build Processor Server Module

Append a custom synchronous process to the build. Occurs on the Server after the build has been returned by the Agent.

command decorator

1.x

2.3

Command Decorator Module

Allows additional parameters to be added to the command line of a builder before a build occurs.

preBuildQueuedAction

1.x, 2.x

2.1

Pre-Build Queued Action

Prepends a custom synchronous process to the build. Occurs before a build is queued.

preBuildAction

1.x

1.1

Pre-Build Action Module

Prepends a custom synchronous process to the build. Occurs before the builder has run.

postBuildCompletedAction

2.x

2.6

Post-Build Completed Action Module

Add a custom asynchronous 'build context'-aware action after the build process has completed and the build results have been saved.

preChainAction

1.x, 2.x

2.7

Pre-Chain Action Module

Prepends a custom synchronous process before the chain starts executing

postChainAction

1.x, 2.x

2.7

Post-Chain Action Module

Prepends a custom synchronous process after the chain finishes executing

preStageAction

1.x, 2.x

2.7

Pre-Stage Action Module

Prepends a custom synchronous process before the stage starts executing

postStageAction

1.x, 2.x

2.7

Post-Stage Action Module

Prepends a custom synchronous process after the stage finishes executing

preJobAction

1.x, 2.x

2.7

Pre-Job Action Module

Prepends a custom synchronous process before the job starts executing

postJobAction

1.x, 2.x

2.7

Post-Job Action Module

Prepends a custom synchronous process after the job finishes executing

repository

1.x

1.1

Source Repository Module

Add a custom source repository.

triggerReason

1.x

2.0

Trigger Reason Module

Add a new trigger reason.

Notification Plugin Modules​

Module Type

Plugin Framework Version

Since Bamboo version...

関連ドキュメント

説明

notification-condition

1.x, 2.x

1.1 〜 2.2

Notification Condition Module

Add new notification condition.

notificationType

1.x, 2.x

2.2

Notification Type Module

Add a new notification type

notificationRecipient

1.x, 2.x

2.2

Notification Recipient Module

Add a new notification recipient type.

Bamboo Event Listeners​

Module Type

Plugin Framework Version

Since Bamboo version...

関連ドキュメント

説明

bambooEventListener

1.x, 2.x

2.2

Bamboo Event Listeners​

Register an event listener against any Bamboo Events.

User Interface Plugin Modules​

Module Type

Plugin Framework Version

Since Bamboo version...

関連ドキュメント

説明

additionalBuildConfigurationPlugin

1.x, 2.x

2.7

Additional Build Configuration Module​

Register additional configuration UI on the Miscellaneous tab of the Configuration of a Job or Plan

レポート

2.x

1.0

Report Module

Defines a report of build telemetry data.

web-item

1.x, 2.x

1.0

Web Item Module

Add new links to the Bamboo interface.

web-section

1.x, 2.x

1.0

Web Section Module

Add a new section to the Bamboo interface.

web resource

1.x, 2.x

2.3

Web Resources

Permits web resources to be included with a plugin.

webRepositoryViewer

1.x, 2.x

2.5

Web Repository Viewer Module

Renders commit information to include web repository links and information.

xwork

1.x, 2.x

1.0

XWork Plugin Module

XWork actions and views bundled with the plugin. This enables building generic user interfaces.

System Plugin Modules​

Module Type

Plugin Framework Version

Since Bamboo version...

関連ドキュメント

説明

capabilityTypeModule

1.x, 2.x

2.7

Capability Type Module​

The Capability Type Module is used for registering custom capabilities

component

1.x

2.6

Component Module

Enables you to add components to Bamboo's internal component system (powered by Spring).

downloadable resource

1.x, 2.x

2.3

Downloadable Plugin Resources

Permits downloadable resources to be included with a plugin.

indexReader

1.x, 2.x

1.0

Index Reader Module

Reads out custom index information written by the postBuildIndexWriter from the index.

postBuildIndexWriter

1.x, 2.x

1.0

Post Build Index Writer Module

Writes custom build data into the index for report generation.

postChainIndexWriter

1.x, 2.x

2.7

Post Chain Index Writer Module​

Writes custom chain data into the index for report generation.

Setting up a Bamboo Plugin Project

Refer to the Getting started with Atlassian plugins​ guide for information on how to set up a Bamboo plugin using the Atlassian Plugin Archetypes​. You will require Maven 2 and JDK 5.

If you have a Commercial License you can obtain the Bamboo Source code. Refer to the Building Bamboo from source page for more information on how set this up.

Testing your Bamboo plugin.

Plugins in Bamboo are not dynamically loadable. They must be installed in Bamboo's WEB-INF/lib and the application restarted. The Atlassian Plugin Maven Archetypes come with a profile called plugin-debug which makes testing your plugin easy. Running the command

mvn -Pplugin-debug

will compile your plugin's classes, create a jar in the /target directory, download a copy of the Bamboo war, copy the plugin jar into Bamboo's WEB-INF/lib directory and start up Bamboo. Maven will also install some default data such as the license and database configuration.

Bamboo will be running at http://localhost:1990/bamboo, so you can go directly there in your browser and see your latest changes. You'll be able to log in with the username admin and the password admin.

As you make changes, you'll have to kill the Bamboo process (ctrl-c) and then run mvn -Pplugin-debug again.

When you run Bamboo with the plugin-debug profile, it is automatically configured to accept a remote debugger. So you'll want to create a remote debug target​ in your IDE for your plugin and/or the bamboo source.

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. お楽しみください!

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-actions-plugin.xml - the built in per-plan build expiry configuration
  • 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 JIRA issue integration.
  • 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-repository-plugin.xml - definition for the CVS, SVN and Perforce repositories shipped with Bamboo.
  • system-triggerReason-plugin.xml - definition of all the built in build trigger reasons such as manual build, dependency build and Scheduled build.
  • 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. 

詳細情報


  • ラベルなし



Log a request with our support team.



Raise an issue for our developers.



See answers from the community.



Blog and update our documentation.

Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 2.5 Australia License.