Migrating Bamboo 7.X.X to Bamboo 8.X.X


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. See Cloning a Bamboo instance.

  2. Follow the upgrade steps on the cloned Bamboo instance as described below 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.


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

a. 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.

b. Upgrade License in Bamboo (only when upgrading to DATA CENTER)

  1. Go to Administration > License Details.

  2. Enter your Bamboo Data Center license key. 

c. 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.

d. 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.

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.

  • 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: 


  1. The Mac installer deletes the previous version of Bamboo.

  2. Follow the Mac OS X install instructions.


  1. Delete your old <bamboo-install> directory to remove any legacy files.

  2. Follow the Linux install instructions.


  1. The Windows installer deletes the previous version of Bamboo.

  2. Follow the Windows install instructions.

  3. Configure Bamboo to run as a service on Windows, using the service.bat executable.

3. Configure the new Bamboo instance

a. 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

    NOTE: For Bamboo 5.1 and earlier, the file path is:

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

b. Update any installed apps

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

  • Check if all apps are compatible with the new version of Bamboo.

  • Update any apps that are out-of-date.

  • Disable any apps that are incompatible with the new version of Bamboo.

c. 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.

If you're upgrading Bamboo from a version earlier than 8.0 to 8.0 or later, and you are also upgrading the Java version on your Remote Agents from 8 to 11, you need to either update wrapper configuration manually or download a new Remote Agent JAR from your upgraded Bamboo and reinstall the wrapper.

d. 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:


Location in Bamboo installation


setenv.bat (Windows) または setenv.sh (Linux)


Configuring your system properties



Modified if you had integrated Bamboo with Crowd




e. 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.

After that process the instance is now in 8.X.X version, if you don’t want Bamboo in cluster then proceed to “5. Start Bamboo”.

Bamboo configured in that way will have all Data Center features when you use Data Center licence in Administration → License Details

4. Install Bamboo Data Center in a cluster

See Install Bamboo Data Center

5. 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. See Version-specific upgrade notes


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

最終更新日 2021 年 8 月 4 日


Powered by Confluence and Scroll Viewport.