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

Unknown macro: {spacejump}

of Bamboo, or visit the latest Bamboo documentation.

This page describes how to upgrade your Bamboo installation to the latest version. We strongly recommend that you upgrade Bamboo by performing the steps below.

Note that:

  • This upgrade process does not perform an in-place upgrade, but installs the new version of Bamboo into a fresh installation directory. The new Bamboo uses your existing Bamboo home directory and external database.
  • For production environments 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.

Recommended upgrade path

update path

When upgrading from Bamboo 4.0 and later, you can upgrade directly to the latest version of Bamboo:

4.0 +  LATEST (5.8)

When upgrading from earlier than Bamboo 4.0, you must upgrade to any of Bamboo 5.0–5.7 before upgrading to Bamboo 5.8:

PRE 4.0 5.0--5.7 LATEST (5.8)

When upgrading from very old versions of Bamboo you must follow this upgrade path:

OLDER VERSIONS 2.0.6 2.6.3 2.7.4 5.0--5.7 LATEST (5.8)

You do not need to downgrade before upgrading.

1. Review the upgrade notes

There are specific upgrade notes further down this page for each version of Bamboo. 

You should read the relevant sections for each version between your current version of Bamboo and the version you are upgrading to.

2. 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. Notice that Bamboo needs to be stopped before exporting your external database.

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

When Bamboo is 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.

3. Download and install Bamboo as usual

This upgrade process does not perform an in-place upgrade, but installs the new version of Bamboo into a fresh installation directory. The new Bamboo uses your existing Bamboo home directory and external database.

Check that you have all the system requirements for the new version of Bamboo, to avoid any trouble.

See also the End of support announcements for Bamboo.

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

 

4. 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. Update any plugins that are out-of-date, and disable any plugins that are incompatible with your new version of Bamboo.

Automatic update of remote agents

For Bamboo 3.2 and later, remote agents are updated 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 update tasks that will run when you start up Bamboo. Please consult your database documentation to ensure that you have configured your database appropriately.

5. Start Bamboo

Start Bamboo

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

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

A Bamboo update may require a reindex.

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.

Version-specific upgrade notes

This section provides specific upgrade notes for each version of Bamboo. These notes supplement the primary upgrade guide above.

You should read the relevant sections for each version between your current version of Bamboo and the version you are updating to.

Upgrading to Bamboo 5.8

Please also see:

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.

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

 

Upgrading to Bamboo 5.7

Please also see:

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 behaviour. The legacy Bamboo 5.6 behaviour for expiry is deprecated and will be removed in a future release.
Read more about global expiry in Bamboo 5.7.

Upgrading to Bamboo 5.6

Please also see:

Stash notifications and the Stash web repository type are deprecated

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

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.

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 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 update your native Git, if you have Git 1.7.1 installed (especially those who use RHEL 6 or CentOS).

Please also see:

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

Note that Bamboo will run a full reindex after updating.

Please also see:

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.

 

Troubleshooting

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

  • Did you encounter a problem during the Bamboo update? Please refer to the guide to troubleshooting updates in the Bamboo Knowledge Base.
  • If you encounter a problem during the update 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.
  • No labels