This is the documentation for Bamboo 5.5. View this page for the

Unknown macro: {spacejump}

of Bamboo, or visit the latest Bamboo documentation.

This page describes how to upgrade Bamboo from a previous version.

  • For an overview of the latest and greatest Bamboo release, see Bamboo releases.
  • For production environments we recommend that you test the Bamboo upgrade on a QA server before deploying to production.

Please also read:

On this page:


Recommended upgrade path

Upgrade path

The recommended upgrade path for Bamboo is:

OLDER VERSIONS → 2.0.6 → 2.6.3 → 2.7.4 → LATEST (5.5)

Note: There is no requirement to downgrade before upgrading.

Bamboo upgrade steps

This section provides general instructions for upgrading Bamboo. See also the specific notes on this page for the version of Bamboo you are upgrading to. We strongly recommend that you upgrade Bamboo by following these steps:

Step 1. Export and back up Bamboo data

Export the Bamboo database

In Bamboo, export your Bamboo database, for backup purposes. See Exporting data for backup for instructions. Note that this may take a long time to complete depending on the number of builds and tests in your system.

If you are using an external database, then use the native database backup tools to acquire a database dump.

Stop Bamboo

Stop Bamboo as usual.

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

Back up the Bamboo configuration

With Bamboo shut down, back up your <Bamboo-home> directory, which includes the builds and configuration directories.

Click Administration, and then System Information (under 'System') in your Bamboo instance, and note the location of the 'Bamboo home', 'Build path' and 'Configuration path' directories (under 'Bamboo paths'):

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

Step 2. Download and install Bamboo as usual

 

  • Make sure that your  <Bamboo-install> directory is either a new directory, or else delete your old  <Bamboo-install> directory before you begin, as legacy files may cause problems.
  • The  <Bamboo-home> directory must be different from the <Bamboo-install> directory. This will ensure that your data is not lost when upgrading or re-installing Bamboo.
  • Ensure that you point the new installation to your old <Bamboo-home> directory, by changing the path in the file at <Bamboo-install>/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).

On Mac OS X

On Linux

On Windows

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

The WAR distribution is no longer distributed

Since Tomcat is now shipped with Bamboo, and Tomcat is the only application server we officially support, the EAR/WAR edition of Bamboo is no longer distributed from www.atlassian.com.

If you wish to get the WAR file, you can do so by downloading it at this url (replacing $VERSION with the version you wish to download):

https://maven.atlassian.com/content/repositories/atlassian-public/com/atlassian/bamboo/atlassian-bamboo-web-app/$VERSION/atlassian-bamboo-web-app-$VERSION.war

 

Step 3. Configure the new Bamboo instance

Reconnect external user directories

You only need to perform this step if either of the following apply:

  • LDAP integration — If you had previously integrated Bamboo with LDAP/AD, copy your old ../<Bamboo-install>/webapp/WEB-INF/classes/atlassian-user.xml to it's new location. Starting with version 3.2, the atlassian-user.xml file will be stored at {BAMBOO-HOME}/xml-data/configuration/. Please replace the existing file using your old atlassian-user.xml. 
  • Crowd integration — If you had previously integrated Bamboo with Crowd, you will need to re-enable Crowd integration. For details please see Integrating Crowd with Bamboo.

Update any installed plugins

If you are using any plugins other than the ones that ship with Bamboo, check that each one is compatible with the new version of Bamboo. Upgrade any plugins that are out-of-date, and disable any plugins that are incompatible with your new version of Bamboo.

Automatic upgrade of remote agents

For Bamboo 3.2 and later, remote agents are upgraded automatically. The remote agent can automatically detect when a new version is available, and has a special classloader that downloads the new classes from the server.

See also the Bamboo remote agent installation guide.

Configure the context path

If you had a context path configured for your Bamboo instance (http://hostname:[port]/context_path), please follow the steps from here: Changing Bamboo's root context path.

Check database access permission

Before starting Bamboo, ensure that Bamboo has  write access to your database. This is required to complete the upgrade tasks that will run when you start up Bamboo. Please consult your database documentation to ensure that you have configured your database appropriately.

Step 4. Start Bamboo

Start Bamboo

Once you have installed Bamboo and set the bamboo.home property, start Bamboo. The upgrade process will be performed when Bamboo starts up. You will not see the Setup Wizard.

Monitor the atlassian-bamboo.log to ensure that the upgrade process completes successfully.

Reindex Bamboo (if indicated in the upgrade notes for the new version)

Bamboo maintains an index of its build results. This allows Bamboo to display aggregate build results information across builds. You may need to perform a re-index of Bamboo if the upgrade process requires it. This step may or may not be required (depending on the upgrade versions). Also note that you will only need to do this if you have existing data in Bamboo.

Note that you will be unable to access reporting features while re-indexing takes place.

To re-index, go to Administration, then Indexing (under 'System'). 

Depending on the number of builds and tests you may have, the indexing process may take a significant amount of time. During this period, Bamboo will not be available. Also, it is advisable to ensure that all you have disabled all build queues (or all agents, if you are upgrading from Bamboo 2.0 or later), and that no builds are in progress when you start the re-indexing process. If you have a large instance, it is recommended that you reindex overnight.

Upgrading to Bamboo 5.5

A full re-index is not required with this upgrade.

  • We recommend that you add OAuth authentication (in addition to existing authentication) to any existing application links between your Bamboo and Stash servers. If you have previously integrated Bamboo with Stash, you will probably have Basic HTTP authentication configured for your link. The new Stash 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 upgrade your native Git, if you have Git 1.7.1 installed (especially those who use RHEL 6 or CentOS).

Please also see:

Known issues

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

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 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 rest assured that we are working on a permanent solution to this issue.

Upgrading to Bamboo 5.4

A full index will be required after upgrading

Please execute a full re-index after upgrading Bamboo. The re-index will run in the background, however note that reporting features will not be available while the re-index process is underway.

Please also see:

Known issues

Installer package on MAC OX 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.

Developing for Bamboo

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

Troubleshooting

If something is not working correctly after you have completed the steps above to upgrade your Bamboo installation, please check for known Bamboo issues and try troubleshooting your upgrade as described below:

  • Did you encounter a problem during the Bamboo upgrade? Please refer to the guide to troubleshooting upgrades in the Bamboo Knowledge Base.
  • If you encounter a problem during the upgrade and cannot solve it, please create a support ticket and and attach your atlassian-bamboo.log so we can help you find out what's gone wrong.

 

 

Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 2.5 Australia License.