Atlassian Upgrade Best Practices

30 april 2020
With this blog we share some of our insights and experiences with upgrading products from the Atlassian stack. With years of experience with upgrades in different environments and configurations we have gained a deep knowledge on how to successfully tackle the upgrade process.

When managing your on-premise Atlassian server of Data Center (DC) software this is a topic that you probably will run into on a regular basis. We, as TMC ALM, have good experience with the subject as we install, service and support our customers with Atlassian throughout the complete lifecycle. With this blog we share some of our insights and experiences with upgrading products from the Atlassian stack. With years of experience with upgrades in different environments and configurations we have gained a deep knowledge on how to successfully tackle the upgrade process.

Why Upgrade?

Why would you upgrade in the first place?

  • New features (see also our monthly blog by our colleague Rick van Twillert)
  • Bug fixes, vulnerability and security risks. 
  • End of Life, the date when your product becomes unsupported (see al actual EOL dates here )

If you would like to keep upgrades to a minimum but still maintain long term support, then consider the Enterprise releases that are available for the bulk of the Atlassian tools. These are releases that will keep getting bug fixes and security updates for the next two years. 

You can find the latest overview here.

When to Upgrade?

It depends…

We would rank them by the following criteria (high to low):

  • Security improvements
  • New functionality and or features
  • Fixed bugs
  • Size of the organization and it’s impact
  • Acceptable downtime
  • Available downtime windows
  • External factors like mergers or broken API’s, integration with 3rd party tools

And last… one organization can have a more dynamic or demanding environment then the other.

In general we advise our customers to schedule an upgrade twice per year. Additionally we see that there are also some unplanned upgrades due to available security releases or bug fixes. For customers having connected their Atlassian stack to the public internet this is especially important. 

Preparation is key

Preparation is the key to a successful and stress free upgrade of your Atlassian toolstack. That’s why Atlassian already has a some good blogs on the subject before upgrading your toolset. Below is small selection. Even though they seem to be geared to Jira they do contain a lot of general topics to think of. 

First step would be to get all the information on the changes and release notes. Research all the information and expected impact. 

Also think of a communication plan, involving people in your organisation related with : IT, (key) users, user community

And last perform a system health check. Ensure that your system is problems that will cause even bigger problems after the upgrade or could even fail your upgrade. It also makes it easier to find potential problems after the upgrade.

TMC ALM also offers Healthchecks ( )  and we can advise or report on how to proceed.

We generally advise to perform such a health check before each upgrade. Typically twice per year.


A sandbox environment is a must when test-driving upgrades. It allows you to safely prepare and test your upgrade process without interfering with the production environment and keep downtimes to during the upgrade to a minimum.

Ideally, it is configured identical to the production environment and is priceless. Even though you could upgrade your tools untested in a production environment – and roll back when things go bad – it is not something that is advised.

The sandbox environment is also handy to test add-ons and see the impact of these add-ons or upgrades of add-ons. It also helps to keep the production environment clear with all kind of temporary data. 

Specially with large instances where people and depended or where a lot of systems hook into your Atlassian tools using scripts and or externals tools. Also when an upgrade is a platform upgrade (i.e.. version 6 to 7) you really want to make sure you covered all your angles. A near-like production copy can make life so much easier.

Ideally the sandbox environment has the identical database, machine (memory and CPU), network, user database, add-ons and content as the production one. So it can mimic the production environment as much as possible. Don’t forget your site’s specific customizations as well.

Atlassian has supplied you with free development licenses which allow you to correctly license your test environment. 

Three types of upgrade

Atlassian differentiates three types of releases:

  • Bug fix
  • Feature
  • Platform (i.e. API changes)

The numbering format is : <platform>.<feature>.<bugfix>

So depending on the planned upgrade the scope of the testing can be determined.

Preparation Checklist

Before starting your preparations, make sure all your licenses are valid. Expired licenses do not cater for upgrades except for the version valid for the expiry date. Also check your add-on licenses. As they might need to be upgraded as well during the process. As TMC ALM we can deliver licences and optionally ensure they are co-termed/synchronized to a single date.

  • Read the release and upgrade notes
    • Does any of the functionality change?
  • Does the new version still support the existing system requirements?
  • Health check. Is your setup running without problems? Now is the time to fix that. 
  • Set a freeze for your production environment, no changes allowed before the scheduled upgrade that could disturb the current status
  • Inform and check with your stakeholders on the pending outage and or impact.
    • Advantage of a Data Center implementation: outage only with platform upgrades.
  • Define your acceptance test, what defines a successful upgrade?
  • What is your roll-back scenario if things go bad?
  • Setup a runbook

Data Center Upgrades

Data Center upgrades can have benefits over on-premises upgrades, especially the latest Jira release (7.3 and up).

With the recent Jira Data Center releases you will be able to upgrade with Zero Downtime! More details can be found here.

This is a feature that really distinguishes the Data Center deployment of Jira over server and we are sure that this will be the norm for all other future Data Center products.

Last Steps before D-day checklist

  • Perform a backup (don’t forget to test your back-up first) 
  • Inform your users upfront 
    • the Jira and Confluence banners are excellent tools to inform your users. 
    • Ideally inform them of the bug-fixes and new functionality to get the buy-in
  • Set a time slot ( out of office hours if needed )
  • Disable add-ons during upgrade, as they potentially can interfere with upgrades. 
  • Optionally: make your site read-only during the upgrade process


Most of the time the upgrades can be easy. Try to keep focused on the job, even though most of the time will be waiting for the process to complete.

Communicate, to inform your users. So all related users are up-to-date and avoiding handling time-consuming calls from end-users about the status of the upgrade.

Most of the time they appreciate to know if the upgrade is started, in progress or successfully completed. Again the announcement banners can be a good way to inform your users. Or have a product like Atlassian Statuspage that can help you with reporting the status of your (IT) environment in general.

All the steps are written down in the runbook so this can be re-used during the next upgrade. Making it even easier to perform the process.

Tips and Tricks

  • Try to use an external back-up tool instead of the build in tools. The build in tools can be resource intensive, can cause performance issues and possibly result in inconsistent backup sets. Also the build in tools do not cover program specific configurations like database and Java memory settings.

Atlassian Support Offerings

Sometimes after the best preparation it is still possible that things come to a halt or problems arise. It is good to know that TMC ALM or Atlassian support is here to resolve your problems.

For the most demanding customers Atlassian also has a several support options that can you give you extra support on top of the standard offering. For example 24×7 phone access to a engineer in case you run into problems. A detailed support offering can be found here :

Contact TMC ALM for your Atlassian Support offerings


After the upgrade went successful it is good to celebrate your success and enjoy your brand new software. 

How to never upgrade again?

There is one last tip that you don’t want to miss out on. Consider moving to Atlassian Cloud!

This way you will never have to go through the hassle of upgrades again. When running on cloud you will be sure that Atlassian keeps your software and add-ons up-to-date while you work.

Atlassian is also investing heavily into their cloud offerings and as an Atlassian Platinum Partner we find more and more customers moving from on-premises to cloud products.

And there are other advantages to cloud:

  • No need to own IT infrastructure needed like cpu, memory and storage
  • 99.9% update (premium contract)
  • Scales > 1000’s of users
  • Out the box: SAML/SSO/2FA/AD sync included (Atlassian Access)
  • When migrating to cloud the existing server license can be used

Considering migrating from Server to Cloud? Contact TMC ALM as we have deep knowledge on successfully migrating server instances to cloud

As an existing on-premises customer you might be eligible to try out cloud for free or at a reduced rate. Contact TMC ALM for more details on what the possibilities are for your instance.


We hope these tips and tricks can be of help for your upgrades. Remember to contact us if you have any (support) questions. We also want to mention that we offer an support contract to cover your upgrades. Based on your wishes and needs we perform a health-check and tooling upgrade one or more times per year. Of course we also pro-actively inform you of any security critical updates. Additionally we offer Server to Cloud migration services. Please feel free to reach out to us if you want to receive more information about our services.