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
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.
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
- 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 → 5.14 → 6.5 → LATEST
- When upgrading from earlier than Bamboo 5.0, follow this upgrade path:
4.0--4.4 → 5.14 → 6.5 → LATEST
- When upgrading from Bamboo 5.0 and later, follow this upgrade path:
5.0-5.13 → 5.14 → 6.5 → LATEST
- When upgrading from Bamboo 5.14 and later, follow this upgrade path:
5.14+ → 6.5 → LATEST
Before you begin
- Read the specific upgrade notes for your version of Bamboo.
- Read End of support announcements for Bamboo.
- Check whether the system where you are going to install the new Bamboo instance meets the requirements .
- Check whether any add-ons may require an update.
- Only import data to an instance running the same version.
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 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
configuration directories. You can compress it into a .zip file.
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.
- 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
Follow these guidelines to install a new Bamboo instance:
- The Mac installer deletes the previous version of Bamboo.
- Follow the Mac OS X install instructions.
- Delete your old
- Follow the Linux install instructions.
- 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
3. Configure the new Bamboo instance
Set the home directory for the new Bamboo instance
<home-directory> to use the
<home-directory> of the original Bamboo instance:
- Go to the new Bamboo instance <bamboo-install> directory. It is the directory where you installed Bamboo.
For Bamboo versions prior to 5.1, the file path is:
- Set the
bamboo.homevariable 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.
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)
|Configuring your system properties|
|Modified if you had integrated Bamboo with Crowd|
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
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
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.
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.
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.
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.
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.
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.
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 188.8.131.52 or later.
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.
If you followed the documentation and you still have problems with the upgrade process: