General upgrade guidelines in Bamboo
You can upgrade Bamboo by installing a new version of Bamboo and setting it up with the configuration of the original Bamboo instance. 
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 binaries aren't installed in the same directory as the original Bamboo binaries, so that you don't lose any changes made to scripts and configuration files inside the Bamboo installation directory. |
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.
If you are a Bamboo app developer, see our Bamboo API Changes by Version guide, which outlines changes in Bamboo that may affect Bamboo apps compiled for earlier versions of Bamboo.
We recommend that you test the Bamboo upgrade on a QA server before deploying to production.
It’s not possible to downgrade to an older version of Bamboo. To revert back to a previous version, restore it from the last backup or snapshot (including the database).
Before you begin
Before you start the upgrade, make sure that you meet all of the following prerequisites:
Determine the correct upgrade path
Upgrading older releases of Bamboo may require doing several intermediate upgrades to ensure backward compatibility. Choose the right upgrade path depending on which release of Bamboo you’re currently on:
If you’re on a release of Bamboo older than 2.0.6, follow this path:
current → 2.0.6 → 2.6.3 → 5.7.x → 5.14.x → 6.5.x → 8.0.12 → 9.6.x
If you’re on Bamboo 2.6.3 through 3.4.x, follow this path:
current → 5.7.x → 5.14.x → 6.5.x → 8.0.12 → 9.6.x
If you’re on Bamboo 4.0.x through 5.13.x, follow this path:
current → 5.14.x → 6.5.x → 8.0.12 → 9.6.x
If you’re on Bamboo 5.14.x through 6.4.x, follow this path:
current → 6.5.x → 8.0.12→ 9.6.x
If you’re on Bamboo 6.5.x through 7.2.x, follow this path:
- current → 8.0.12 → 9.6.x
If you're on Bamboo 8.x.x through 9.5.x, upgrade to 9.6.x directly.
Read the release and upgrade notes
To learn more about all the new features and changes impacting the upgrade progress, check out:
Upgrade to Bamboo Data Center
Starting from version 9.5, new releases of Bamboo will be available only to Data Center customers. If you're currently on Bamboo Server, you'll need to upgrade to Bamboo Data Center:
- Check the infrastructure and hardware requirements for clustering with Bamboo Data Center
- Learn more about the changes that will be made to your home directory during the upgrade
- Upgrade from Bamboo Server to Bamboo Data Center
Check platform requirements and end-of-support announcements
Go to:
Check installed app compatibility
Make sure that the apps you've installed are compatible with the release of Bamboo that you want to upgrade to.
To do this, run the Bamboo update check:
- In the upper-right corner of the screen, selectAdministration> Manage apps.
- At the bottom of the Manage apps page, select Bamboo update check.
- Select the release that you want to upgrade to, and then select Check.
Learn more about apps and the Universal Plugin Manager (UPM)
1. Export and back up the existing Bamboo data
Create a support zip
Create a support zip containing logs from your instance, diagnostic, and configuration information. If you run into problems during the upgrade, you can send this file to our support team to help them understand how your application is configured and to troubleshoot your problem efficiently.
Learn how to create a support zip
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 Connect 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 <b> directory, which contains the amboo-home builds and configuration directories. You can compress it into a .zip file.
Select 
> 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 version
To upgrade Bamboo, you must install a new Bamboo instance in a new directory that's different from the installation directory of the Bamboo instance you're upgrading.
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 installation directory.
Follow these guidelines to download and unpack a new Bamboo version:
Download Bamboo
Download the file for your operating system from https://www.atlassian.com/software/bamboo/download:
tar.gzfor MacOS or Linux distributions.zipfor Windows.
Create the installation directory
Create an installation directory and extract the downloaded file there. The path to that directory will now be referred to as <bamboo-install-dir>.
3. Configure the new Bamboo instance
Set the home directory for the new Bamboo instance
Set the path to the Bamboo home directory according to your operating system:
To set the home directory path on Linux:
Go to
<bamboo-install-dir>/WEB-INF/classes<bamboo-install-dir>is the location where you've extracted the downloaded.tar.gzfile. For example:/var/bamboo/bamboo-9.6.0Open the
bamboo-init.propertiesfile in a text editor and set thebamboo.homevariable to the previously used home directory path. For example:bamboo.home=/var/bamboo/bamboo-homeIf you're upgrading a clustered Data Center instance of Bamboo, set the
bamboo.shared.homevariable to the previously used shared home directory path.
To set the home directory path on Windows:
Go to
<bamboo-install-dir>\WEB-INF\classes<bamboo-install-dir>is the location to which you've extracted the downloaded.zipfile. For example:C:\bamboo\bamboo-9.5.0Open the
bamboo-init.propertiesfile in a text editor and set thebamboo.homevariable to the previously used home directory path. For example:bamboo.home=C:\\bamboo\\bamboo-homeIf you're upgrading a clustered Data Center instance of Bamboo, set the
bamboo.shared.homevariable to the previously used shared home directory path.
Install a JDBC driver
If the JDBC driver for your database isn't bundled with Bamboo, you need to install it for the new Bamboo instance yourself. See Connect Bamboo to an external database for detailed instructions.
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) |
| Configuring your system properties |
seraph-config.xml |
| Modified if you had integrated Bamboo with Crowd |
server.xml |
| 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
Install Windows service
If previous version of Bambo was executed as Windows service then configure Bamboo to run as a service on Windows, using the service.bat executable.
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.
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.
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.
Automatic update of remote agents
Since Bamboo 6.10, remote agents automatically detect when a new version is available and download new classes from the server. However, Bamboo 6.10 also updated the remote agent wrapper, which means that for upgrades from versions earlier than 6.10, you'll have to manually reinstall the wrapper on your remote agents.
Additionally, remote agents now support Java 17. If you want to migrate any of your existing remote agent instances to Java 17, you'll need to reinstall the affected remote agent wrappers.
For more information, see Bamboo remote agent installation guide.
Troubleshooting
If you followed the documentation and you still have problems with the upgrade process:
- Check other Knowledge Base articles.
- Ask questions at https://community.atlassian.com/.
- You can also create a support ticket. To help us address the issue, attach the
atlassian-bamboo.log and Support zipfile to the ticket.