Bamboo upgrade guide

You can upgrade Bamboo by installing a new version of Bamboo and setting it up with the configuration of the original Bamboo instance.

On this page

Overview

The recommended paths for upgrading Bamboo to a new version differ depending on whether you want to move to a new server or not:

Upgrading Bamboo locally Upgrading Bamboo with a move to a new server

Perform the steps as described on this page.

Make sure that your new Bamboo instance is not installed in the same directory as the original Bamboo instance.

  1. Clone your Bamboo instance into the new location.
  2. Perform the upgrade steps on the cloned Bamboo instance as described on this page.

The cloned instance on the new server is referred to as original Bamboo instance.

In both scenarios, the new Bamboo instance uses the home directory and the database of the original Bamboo instance.

We recommend that you test the Bamboo upgrade on a QA server before deploying to production.

If you are a Bamboo plugin developer, see our Bamboo API Changes by Version guide, which outlines changes in Bamboo that may affect Bamboo plugins compiled for earlier versions of Bamboo.

Before you begin

Determine your upgrade path

Upgrade path

  • When upgrading from very old versions of Bamboo, follow this upgrade path:

OLDER VERSIONS  2.0.6  2.6.3 → 2.7.4 →  5.0--5.7  6.5   LATEST

  • When upgrading from earlier than Bamboo 5.0, follow this upgrade path:

4.0--4.4  →  5.14  LATEST

  • When upgrading from Bamboo 5.0 and later, follow this upgrade path:

5.0-5.13  5.14  LATEST

  • When upgrading from Bamboo 5.14 and later, follow this upgrade path:

5.14+  LATEST


Before you begin

tip/resting Created with Sketch.

The installation path is referred to as <bamboo-install> and points to the directory into which you extracted the Bamboo package. It is different from <bamboo-home>, which points to the directory where Bamboo data is stored.

1. Export and back up the existing Bamboo data

Export the Bamboo database

There are two database backup scenarios, depending on whether you are using an embedded or external database.

Embedded HSQL database External database

Create an export .zip file for the original Bamboo instance. For more information, see Exporting data for backup.

The export may take a long time to complete and may require a large amount of disk space, depending on the number of builds and tests in your system.

HSQL is not recommended for production Bamboo instances.

Use native database tools to create a backup. For more information about external databases, see Connecting Bamboo to an external database.

Stop Bamboo

Stop the original Bamboo instance.

If you have Bamboo running as a Windows service, uninstall the service by using the UninstallService.bat executable that came with your Bamboo instance.

Back up the Bamboo configuration

When the original Bamboo instance is shut down, back up your <bamboo-home > directory, which contains the builds and configuration directories. You can compress it into a .zip file.

Viewing Bamboo paths

Go to Administration > System > System information > Bamboo paths. Note the Bamboo home path, Build path, and Configuration path:

For more information about these directories, see Important Directories and Files.

2. Download and install a new Bamboo instance

To upgrade Bamboo, you must install a new Bamboo instance in a  <bamboo-install> directory that is different from the <bamboo-install> directory of the original Bamboo instance .

 This upgrade scenario uses the home directory and the external database of the original Bamboo instance.

tip/resting Created with Sketch.
  • Make sure that the original Bamboo instance is not running before you start the new installation.
  • To prevent data loss during updates or reinstallation, the   <bamboo-home > directory must be different from the  <Bamboo-install > directory.

Follow these guidelines to install a new Bamboo instance: 

MacOS
Linux
Windows
  • The Windows installer deletes the previous version of Bamboo.
  • Follow the Windows install instructions.
  • Configure Bamboo to run as a service on Windows, using the service.bat executable.

3. Configure the new Bamboo instance

Set the home directory for the new Bamboo instance

 Set the <home-directory> to use the <home-directory> of the original Bamboo instance:

  1. Go to the new Bamboo instance <bamboo-install> directory. It is the directory where you installed Bamboo.
  2. Open atlassian-bamboo/WEB-INF/classes/ bamboo-init.properties 

    For Bamboo versions prior to 5.1, the file path is: <bamboo-install>/webapp/WEB-INF/classes/bamboo-init.properties

  3. Set the bamboo.home variable to use the <bamboo-home> path of the original Bamboo instance.

Reconnect external user directories (optional)

If you had integrated the original Bamboo instance with Crowd or LDAP, you must enable the integration for the new Bamboo instance.

For more information, see Integrating Crowd with Bamboo and Integrating Bamboo with LDAP.

Update any installed add-ons

If you installed any add-ons in addition to the pre-installed system add-ons:

  • Check if all add-ons are compatible with the new version of Bamboo.
  • Update any add-ons that are out-of-date.
  • Disable any add-ons that are incompatible with the new version of Bamboo.

Automatic update of remote agents

For Bamboo 3.2 and later, remote agents are updated automatically. Remote agents automatically detect when a new version is available and downloads new classes from the server.

For more information, see Bamboo remote agent installation guide.

 

Migrate your existing Bamboo configurations over to your new Bamboo installation

If you have modified properties in configuration files of your existing Bamboo installation, make the same modifications in your new Bamboo installation. However, because the properties in the configuration files may have changed between versions, you cannot simply copy the configuration files from your existing installation and replace the equivalent files in the new installation.

For each file you have modified in your existing Bamboo installation, you need to manually edit each equivalent file in your new Bamboo installation and re-apply your modifications.

The table below lists the most commonly modified files and their locations within your Bamboo Installation Directory:

File Location in Bamboo installation Description

setenv.bat (Windows) or setenv.sh (Linux)

bin

Configuring your system properties

seraph-config.xml

atlassian-bamboo/WEB-INF/classes

Modified if you had integrated Bamboo with Crowd

server.xml

conf

Modified in the following situations:

Check database access permission

Before you start the new Bamboo instance, make sure that it has the write access to the database, which is required to complete the upgrade tasks.

4. Start Bamboo

Start Bamboo

Once you have installed Bamboo and set the bamboo.home property, start the new Bamboo instance. The upgrade runs automatically.

You can check whether the upgrade was successful in the atlassian-bamboo.log file.

Upgrading Bamboo may require reindexing.

Depending on the number of existing builds and tests, the reindexing process may take a significant amount of time, during which Bamboo will not be available.

Version-specific upgrade notes

The version-specific notes provide additional information to the main upgrade documentation. We recommend reading the version-specific notes for the original and new Bamboo instance versions.


Upgrading to Bamboo 6.7...

Go online to upgrade to 6.7.2

Bamboo 6.7.2 includes a new upgrade task which verifies connection to LDAP for the sake of Embedded Crowd. For that reason, to perform the upgrade, you must be connected to the Internet.

Anonymous users remote repository trigger and Bamboo Specs detection disabled by default 

Both remote repository trigger and Bambo Specs detection and by default disabled for anonymous users in Bamboo 6.7. Access to these by anonymous users is necessary e.g. for using webhooks. To enable it, go to > Overview > Security settings. 

When enabled, Bamboo ignores permissions settings for anonymous user access to those REST endpoints but keep restriction on other REST resources. 

PostgresSQL 9.2 and 9.3 deprecated

Starting from version 6.7, Bamboo deprecates PostgresSQL 9.2 and 9.3. Support for these versions will end in an upcoming release.

Upgrade time

Bamboo 6.7 contains upgrade tasks for changes to the audit log table which can impact the upgrade time. The upgrade time can differ depending on the size of your audit log so plan some extra time when upgrading.

For reference, during our test, an audit log table with 6,5 records in PostgreSQL took 3 extra minutes of upgrade time.


Upgrading to Bamboo 6.6...

New upgrade threshold

We've made some changes to the possible Bamboo upgrade paths. To figure our the best way to upgrade your Bamboo to the latest version, see the upgrade path.

Heroku plugin not supported 

Heroku's API changes rendered the Heroku plugin for Bamboo non-functional and we no longer deploy it with Bamboo. Check this DevCenter article on WAR Deployment for recommended alternatives.

See also:



Upgrading to Bamboo 6.5...

See:

Upgrading to Bamboo 6.4...

Hung Build Killer added to the add-on blacklist

Bamboo 6.4 is shipped with a native mechanism for monitoring builds. For that reason, the Hung Build Killer plugins becomes deprecated. See Add-on blacklist.

See also:

Upgrading to Bamboo 6.3...

Change to the built-in database

Starting with Bamboo 6.3, the built-in HSQL database is replaced by H2. If you store any data in HSQL and want to keep it after the upgrade, you must export the data to XML and import back after you've installed the new version of Bamboo. See: 

The H2 database is fine for evaluation purposes but is somewhat susceptible to data loss during system crashes. For production environments we recommend that you configure Bamboo to use an external database.

See also:

Upgrading to Bamboo 6.2...

See also:

You might also want to check our Bamboo Specs reference documentation.

Upgrading to Bamboo 6.1...

See also:

You might also want to check our Bamboo Specs reference documentation.

Upgrading to Bamboo 6.0...

Microsoft JDBC driver

With Bamboo 6.0, SQL Server jTDS driver is replaced with the official Microsoft JDBC driver. 

If database settings are configured directory in Bamboo, then during 6.0 upgrade it will attempt to update driver settings. In case of customized settings Bamboo instance administrator will be required to manually convert the settings.

If database settings are configured in the container (Tomcat) and Bamboo uses datasource, automatic upgrade will not be possible and instance administration will  be required to manually convert the settings.

To learn more about this change, see here

New library for setting up a JNDI resource for SMTP

Bamboo 6.0 is shipped with the javax.mail-api-1.5.6.jar library. This library needs to copied over to your <Bamboo-install>/lib folder when setting up a JNDI resource for SMTP. For more information, see here.

Changes to Git support

Starting from version 6.0, Bamboo changes support for Git to version 1.8.1.5 or later. 

Upgrading to Bamboo 5.15...

Bamboo 5.15 contains upgrade tasks that can take extra time when moving from earlier versions of Bamboo. Keep this in mind when planning your upgrade outages.

Upgrading to Bamboo 5.14...

New API for VCS repositories

We've rebuilt the repository subsystem, added new plugin points, and introduced new web repository viewers. 

Action required

Before you upgrade to Bamboo 5.14, check for potential plugin incompatibilities, especially if you're using any plugins that aren't officially supported by Atlassian (third-party plugins, plugins developed in-house, or plugins marked as unsupported on Atlassian Marketplace). 

We strongly recommend reporting compatibility issues to the plugin vendor and Atlassian Support.

For details about the API changes, see our developer documentation

Changes in requirements for table names of the external databases

With Bamboo 5.14, we're dropping the lowercase table names requirement for the external database configuration introduced in Bamboo 5.13. For more information, see:

See also

You might also want to check our developer documentation.

Upgrading to Bamboo 5.13...

Bamboo 5.13 introduces stricter verification of the external database configurations which prevents both upgrade and application start:

Microsoft SQL Server The check ensures that the tables in the Bamboo database have correct collation and correct commit isolation, see Microsoft SQL Server.
All DBs except SQL Server

The check ensures that the database engine is correctly configured to be case-insensitive.

Make sure your specific database is configured correctly according to Connecting Bamboo to an external database. For MySQL specifically, this might affect all databases in the instance, see MySQL documentation.

If the check fails

If the check fails and you can't correct your database configuration immediately, you can roll back to the previous installed version of Bamboo without changing anything in your database or home directory configuration.

See also:

You might also want to check our developer documentation.

Upgrading to Bamboo 5.12...

See:

You might also want to check our developer documentation.

Upgrading to Bamboo 5.11...

See:

You might also want to check our developer documentation.

Remember that remote agents must be restarted after the upgrade.

Upgrading to Bamboo 5.10...

Upgrading to Bamboo 5.10

See:

You might also want to check our developer documentation.

Remember that remote agents must be restarted after the upgrade.

Upgrading to Bamboo 5.9...

Changes to Clover Plugin integration

Automatic Clover integration for Maven 2 and Maven 3 tasks has been changed. It has tighter integration and adds Clover goals between goals from an original command so that a build will be performed only once (i.e. it will not run a separate build phase as it did before). Automatic Clover integration will not happen when your Maven task contains the install or deploy commands; this is to protect your repositories from being polluted by instrumented code. Therefore, please check if any of your Maven tasks that use automatic Clover integration use the install or deploy Maven commands. If they do: either disable automatic Clover integration for those jobs, or change the phase to the verify command (or earlier) or set up a dedicated job for Clover. Otherwise, your jobs will not produce Clover's coverage reports.

See also:

Upgrading to Bamboo 5.8...

Hibernate dialect update

When you upgrade to Bamboo 5.8, an upgrade task will run that changes the Hibernate dialect in the bamboo.cfg.xml file. The new dialects are:

org.hibernate.dialect.PostgreSQLDialect
org.hibernate.dialect.HSQLDialect
org.hibernate.dialect.Oracle10gDialect
org.hibernate.dialect.MySQL5Dialect
com.atlassian.bamboo.hibernate.SQLServerIntlDialect

See also:

If you are upgrading from Bamboo versions earlier than Bamboo 4.0, you must upgrade to any of Bamboo 5.0–5.7 before upgrading to Bamboo 5.8.

Upgrading to Bamboo 5.7...

Global deployment expiry

If you are updating to Bamboo 5.7 from 5.6 or earlier and you were previously using build expiry then the Global expiry page in Bamboo looks and works the same as it does in 5.6. In other words you are able to expire builds but not deployments. There is an option to enable deployment expiry however and selecting this option enables the new expiry features introduced in Bamboo 5.7.
Note that this may mean that deployment artifacts and deployment result logs that were previously not being removed will start to be removed. Most likely this is what you want but it's important to be aware of this change.
Note also that enabling deployment expiry is not reversible. If you enable deployment expiry you will be unable to go back to the legacy Bamboo 5.6 behavior. The legacy Bamboo 5.6 behavior for expiry is deprecated and will be removed in a future release.
Read more about global expiry in Bamboo 5.7.

See also:

Upgrading to Bamboo 5.6...

Bitbucket Server notifications and the Bitbucket Server web repository type are deprecated

Bitbucket Server notifications and the legacy Bitbucket Server web repository type are deprecated in Bamboo 5.6, and will be removed in Bamboo 5.7. Use the Bitbucket Server repository integration available in Bamboo 5.6, which is based on application links, to replace that functionality. Read about using Bitbucket Server repositories with Bamboo on Bitbucket Server.

Update time

When scheduling the outage window for the Bamboo 5.6 update, keep in mind that update task 4407 that is executed during the update may take up to 45 minutes to complete on large instances, depending on the size of the VARIABLE_CONTEXT table. For a more precise calculation, assume that 10 minutes are needed to process 15 million records in that table.

Installer package on MAC OS X can not be opened due to code signing requirements 
Note, this issue was found in Bamboo 5.4 and still applies to Bamboo 5.6.

Previously, Mac OS X required binaries to be Developer ID signed in order to run out of the box. Without signing, users would receive a warning that the app isn't from the App Store or a registered Apple Developer. Users were able to apply a work-around to solve this problem.

The latest version of Mac OS X (10.8 and above), however, now reports that the Bamboo installer for Mac is corrupted rather than being blocked by developer ID.

Please see  BAM-11742 - Getting issue details... STATUS  for more information.

  1. The Mac installer will not be available until this has been resolved
  2. There is a temporary work-around available here.

This is a small bug with our installer. Please be assured that we are working on a permanent solution to this issue.

See also:

Upgrading to Bamboo 5.5...
  • We recommend that you add OAuth authentication (in addition to existing authentication) to any existing application links between your Bamboo and Bitbucket servers. If you have previously integrated Bamboo with Bitbucket Server, you will probably have Basic HTTP authentication configured for your link. The new Bitbucket repository type will work with Basic HTTP, but OAuth is a better as it is an impersonating authentication type. For more information, see Configuring authentication for an application link.
  • Git will use --ancestry-path when trying to extract changeset due to  BAM-13760 - Getting issue details... STATUS . Since that command is available for Git 1.7.2 and above (see Release Notes), please update your native Git, if you have Git 1.7.1 installed (especially those who use RHEL 6 or CentOS).

See also:

Upgrading to Bamboo 5.4...

Note that Bamboo will run a full reindex after updating.

Installer package on MAC OS X can not be opened due to code signing requirements

Previously, Mac OS X required binaries to be Developer ID signed to run out of the box. Without signing, users would receive a warning that the app isn't from the App Store or a registered Apple Developer. Users were able to apply a work-around to solve this problem.

The latest version of Mac OS X (10.8 and above), however, now report that the Bamboo installer for Mac is corrupted rather than being blocked by developer ID.

Please see  BAM-11742 - Installer package is "damaged and cannot be reopened" on Mac OS X RESOLVED  for more information.

  1. The Mac installer will not be available until this has been resolved
  2. There is a temporary work-around solution available here.

This is a small bug with our installer, please rest assured that we are working on a permanent solution to this issue.

See also:

Troubleshooting

If you followed the documentation and you still have problems with the upgrade process:

Last modified on Dec 11, 2018

Was this helpful?

Yes
No
Provide feedback about this article

In this section

Powered by Confluence and Scroll Viewport.