Last updated Jul 17, 2025

Bamboo plugin guide

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:

1
2
<!-- 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" plugins-version="2">
    <!-- 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>
        <!-- details of the plugin vendor -->
        <vendor name="Atlassian Software Systems Pty Ltd" url="https://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?

The following types of plugin modules are supported by Bamboo:

Build Lifecycle Plugin Modules

Module TypeSince Bamboo version...DocumentationDescription
buildAgentRequirementFilter2.2Build Agent Requirement Filter ModuleCustomises the list of Agents a plan can be built on.
buildCompleteAction1.0Build Complete Action ModuleAdd a custom asynchronous action after the build process has completed.
buildDefinitionTransformer3.3
buildProcessor1.0Build Processor ModuleAppend a custom synchronous process to the build. Occurs on the Agent (both local and remote) after the builder has run.
buildProcessorServer2.0Build Processor Server ModuleAppend a custom synchronous process to the build. Occurs on the server after the build has been returned by the Agent.
buildTriggerCondition5.14Define condition for trigger execution.
planDeletionInterceptorAction2.7Plan Deletion Interceptor Action ModuleAllows execution of additional actions before plan removal.
planTrigger3.2
preBuildQueuedAction2.1Pre-Build Queued ActionPrepends a custom synchronous process to the build. Occurs before a build is queued.
preBuildAction1.1Pre-Build Action ModulePrepends a custom synchronous process to the build. Occurs before the builder has run.
preDeploymentAction6.4Prepends a custom synchronous process to the environment deployment. Occurs before the builder has run.
postBuildCompletedAction2.6Post-Build Completed Action ModuleAdd a custom asynchronous `build context`-aware action after the build process has completed and the build results have been saved.
preChainAction2.7Pre-Chain Action ModulePrepends a custom synchronous process before the chain starts executing.
postChainAction2.7Post-Chain Action ModulePrepends a custom synchronous process after the chain finishes executing.
preStageAction2.7Pre-Stage Action ModulePrepends a custom synchronous process before the stage starts executing.
postStageAction2.7Post-Stage Action ModulePrepends a custom synchronous process after the stage finishes executing.
preDeploymentQueuedAction*7.2Prepends a custom synchronous process before the environment added to queue.
preJobAction2.7Pre-Job Action ModulePrepends a custom synchronous process before the job starts executing.
prePostTaskActions5.8
postJobAction2.7Post-Job Action ModulePrepends a custom synchronous process after the job finishes executing.
restartFailedStageAction3.2
resumeManualStageAction3.2
repository1.1Source Repository ModuleDefine a custom source repository.
stopOnManualStageAction3.2Action which is executed if build stopped at manual stage.
taskProcessCommandDecorator3.1Allows to add custom logic during execution of existing Task.
taskCondition6.6Define Task condition.
taskType3.1Task Plugin ModuleDefine Task for job or environment.
triggerReason2.0Trigger Reason ModuleDefine trigger reason.
triggerType5.0Define build or environment trigger.
vcsType5.14Define a custom source repository.

Notification Plugin Modules

Module TypeSince Bamboo version...DocumentationDescription
notificationType2.2Notification Type ModuleAdd a new notification type
notificationRecipient2.2Notification Recipient ModuleAdd a new notification recipient type.

Bamboo Event Listeners

Module TypeSince Bamboo version...DocumentationDescription
bambooEventListener2.2Bamboo Event ListenersRegister an event listener against any Bamboo Events.

User Interface Plugin Modules

Module TypeSince Bamboo version...DocumentationDescription
additionalBuildConfigurationPlugin2.7Additional Build Configuration ModuleRegister additional configuration UI on the Miscellaneous tab of the Configuration of a Job or Plan
customEnvironmentConfig6.4Register additional configuration UI on the Miscellaneous tab of the Configuration of an Environment
decorator2.3Configure Sitemesh decorator for pages matched by regexp.
decorator-mapper2.3Configure Sitemesh decorator mappers.
footer2.3Configure custom page footer.
report1.0Report ModuleDefines a report of build telemetry data.
soy-function4.2Defines Soy functions.
struts12.0Struts Plugin ModuleStruts actions and views bundled with the plugin. This enables building generic user interfaces.
top-navigation2.3Pluggable top navigation.
vcsRepositoryViewer5.14Renders commit information to include web repository links and information.
web-item1.0Web Item ModuleAdd new links to the Bamboo interface.
web-item-provider1.0Web Item Provider ModuleAllow plugins to define web-items dynamically in application menus.
web-panel3.0Web Panel ModuleAllow plugins to define panels, or sections, on an HTML page.
web-panel-renderer3.0Web Panel Renderer ModuleAllows plugins to define custom renderer engines for web panels.
web-section1.0Web Section ModuleAdd a new section to the Bamboo interface.
web-section-provider1.0Web Section Provider ModuleAllow plugins to define web-sections dynamically in application menus.
web-resource2.3Web ResourcesPermits web resources to be included with a plugin.
webRepositoryViewer2.5Web Repository Viewer ModuleRenders commit information to include web repository links and information.
xwork1.0XWork Plugin ModuleXWork actions and views bundled with the plugin. This enables building generic user interfaces.

System Plugin Modules

Module TypeSince Bamboo version...DocumentationDescription
artifactHandler5.9Defines artifact handler which handles operations with Job artifacts.
capabilityConfigurator2.5Allows to modify capability settings on the fly
capabilityType2.7Capability Type ModuleThe Capability Type Module is used for registering custom capabilities
component2.6Component ModuleEnables you to add components to Bamboo's internal component system (powered by Spring.
credentialType5.10Define credential type for Shared credentials feature.
dockerHandler6.6
downloadStrategy4.4
freemarkerAllowlist11.0Provides methods and classes allowed to be used at Freemarker templates.
encoder11.0
indexReader1.0Index Reader ModuleReads out custom index information written by the postBuildIndexWriter from the index.
planExecutionGuard9.4
postBuildIndexWriter1.0Post Build Index Writer ModuleWrites custom build data into the index for report generation.
postChainIndexWriter2.7Post Chain Index Writer ModuleWrites custom chain data into the index for report generation.
preRssExecutionAction6.6Allows to execute custom logic before Repository Stored Specs execution.
resource2.3Downloadable Plugin ResourcesPermits downloadable resources to be included with a plugin.
serializableClassWhitelistProvider8.0Provides plugin's classes which are allowed to be serialized during agent-server communication.
vcsCacheHandler11.0Repository cache handler.
velocity-allowlist11.0Provides methods and classes allowed to be used at Velocity templates.
url-reading-web-resource-transformer5.6Stateless web-resource transforms and conditionsStateless transformer for web resources.
userRenameHandler5.7Handler for user rename event.

Other Plugin Modules

Module TypeSince Bamboo version...DocumentationDescription
quickFilterRuleType5.12Quick Filter Rule Type ModuleCustom type of rule used within Bamboo quick filters.

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 3 and Oracle JDK 21 or Adoptium JDK 21.

If you have a Commercial License you can obtain the Bamboo Source code by contacting support team.

Testing your Bamboo plugin.

Follow instructions at Create a HelloWorld plugin project page how to use atlas commands

1
2
atlas-run or atlas-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:6990/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 atlas-debug again.

When you run Bamboo with the atlas-debug command, 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. For Bamboo instance with UPM 6.5.2+ add system property -Dupm.plugin.upload.enabled=true and restart Bamboo (this is required to allow uploading plugins via the UI)
  2. Open UPM UI at http://BAMBOO_URL/plugins/servlet/upm
  3. Upload jar file with your plugin using the "Upload app" button
  4. Enjoy!

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-builderConfiguration-plugin.xml -
  • system-dockerHadler-plugin.xml - the built-in Docker wrapper integration.
  • system-jira-plugin.xml - the built-in JIRA issue integration.
  • system-listeners-plugin.xml - the built-in event listeners for the Bamboo System.
  • system-notifications-plugin.xml - the built-in notification conditions, including all builds, failed builds, after X failed builds.
  • system-quick-filters-plugin.xml - the built-in Quick Filters rule types.
  • system-reports-plugin.xml - the built-in reports of builds grouped by time periods under the Reports tab.
  • system-repository-plugin.xml - definition for the SVN repository shipped with Bamboo.
  • system-servlets-plugin.xml - the built-in servlets and filters definitions.
  • system-shared-credentials-plugin.xml - the built-in shared credentials definitions.
  • 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. 

Further Information

Rate this page: