Back to School Jira Edition: 4 Lessons to inform your next Upgrade

This community post is an offshoot of a talk I gave at Summit this year on Jira upgrades at scale. Check out the recording here!


 There are lots of perks that come with hosting your own Jira instance - having control over your configuration, keeping your data on-premise, customizing your setup, and more. Your unique setup and configuration also means that the upgrade process will look different for everyone.

Upgrading to a new version of Jira Software gives you and your team access to exciting new features, bug fixes, and integration capabilities. And beyond getting your team the latest and greatest features and fixes, upgrading your instance gives you access to performance improvements, compatibility with modern infrastructure and add-ons, as well as fixes for security vulnerabilities.

While there is no denying the value of upgrading regularly, at times the process can be complex and even overwhelming. To set up your next upgrade for success, check out these four upgrade lessons based on the most common challenges that Jira admins encounter.

Looking to start with the basics? Check out the Best Practices Upgrade Guide for Jira Software Server for a full walkthrough of the Jira Software upgrade process, including a downloadable upgrade checklist.


 Let's walk through four upgrade lessons based on the most common upgrade challenges that Jira admins encounter.

Lesson 1: Verify that your upgrade will be successful by upgrading a staging environment that is identical to your production instance. 


It is crucial that your staging environment mirrors your production instance, including all aspects of your Jira configuration, like customizations or database changes. With the mirrored staging environment in place, you will discover issues in a risk-free environment where you have the time to troubleshoot accordingly before proceeding with your production upgrade. 

Without the safeguard of an identical staging environment, teams often learn the hard way that when small details are left out of the planning process, it can result in major upgrade blockers. 

For best practices in establishing staging server environments for Jira applications, check out this article.

(star) Pro tip: In order to set up your staging environment for success, be sure to also track all add-ons and customizations. This ensures that none are overlooked during the staging upgrade. A good way to do this is by exporting a list of all add-ons from the Universal Plugin Manager, which can be accessed by going to > Add-ons as an administrator. A best practice is to also identify and list corresponding stakeholders for each add-on and reach out to them when you are planning your upgrade to make sure the add-ons are still in use. 

Lesson 2: Always create a fresh staging instance for your upgrade.


Always recreate your entire staging environment - including the database - especially if you didn’t personally perform the last Jira upgrade. This gives you the clean slate that you need to replicate the production environment as closely as possible.

(star) Pro tip: When upgrading your staging environment, do a few upgrade dry-runs with the same data. Why? Because data changes over time. A common problem admins run into is completing the staging upgrade too far in advance so the data changes before the upgrade. To prevent this, run an additional staging upgrade as close to upgrade deadline as possible (ideally within week or two).

For larger Jira installations, there are a few other considerations to keep in mind.  Firstly, if multiple teams own Jira, make sure all changes are documented in a central place, like Confluence. Another key consideration is testing the performance of your staging instance. This ensures that your instance will not experience a performance regression and will be able to support larger volumes.  Check out a sample Jira Data Center performance test here

Lesson 3: Check all add-ons for compatibility.


A common misconception is that add-ons will be compatible between feature releases as long as there are no platform changes (like passing Jira 7.0). However, checking add-on compatibility is critical before any and all version upgrades to check which add-ons (if any) require updates before the version upgrade. 

To run an add-on compatibility check, go to > Add-ons > Manage Add-ons, and click "Jira update check" at the bottom of the page. For more details about the add-on compatibility check, click here. If your users rely on particular add-ons more than others, it's also a good idea to prioritize their compatibility when selecting which version of Jira Software to upgrade to. 

If you encounter an incompatible plugin error, follow these steps on how to manage incompatible add-ons

Lesson 4: (Over)communicate with all teams affected by the Jira upgrade and conduct user acceptance testing to understand how teams will be impacted.lastone.png

Being proactive and clear about the upgrade timeline is key to maintaining trust and helping end-users feel confident about changes to Jira. This communication helps users stay productive and allows you to focus on the upgrade itself. 

The most common channels for upgrade communications are the Jira Announcement Banner, email, chat, and physical communications (ie. posters or meetings). Keep in mind that using multiple channels is the most effective way to make sure everyone is in the know. So, the more the merrier!


 As a best practice, be sure to include the following details in each message:

  • Date, time (including timezone) of scheduled upgrade  
  • What is required of users (if anything)
  • How it will impact their Jira Software access 
  • Who to contact with questions or concerns (and their contact info)

Once the test upgrade is completed in the staging environment, conduct user acceptance testing by selecting a sample group of users to test their normal workflow in the staging environment. If you can, select a subset of users from different teams that use varying Jira Software functions. Have them communicate any errors or inconsistencies during testing and ensure they are resolved before proceeding with the upgrade. User acceptance testing is key to understanding how customers will be impacted by the upgrade and will allow you to tailor your communications accordingly. 


 With the right tools and preparation, upgrades are nothing to fear. In fact, upgrades are the key to unlocking Jira’s potential and fostering long-term sustainability at your organization.  

Ready for your next upgrade? Check out what's new in Jira Software here.

We'd love to hear from you - what are your favorite upgrade tips? 



Bastian Stehmann
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
September 6, 2018

My Tip for upgrading is, always have a up-to-date backup before upgrading a production environment, so that you can go back to the old version if any errors occur that can not be resolved, because you never know what will happen, even if you properly tested in a staging environment. 

Vickey Palzor Lepcha
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
September 7, 2018

@Laura Good Read.

1) Upgrade of Staging Environment is always advised - I do that all the time. This is possibly the best way to check how upgrades would go. I have been able to prevent a lot of issues from flowing over to Production.

2) I'd recommend a refresh of Staging Data using Production Backup - maybe you meant the same :-)

3) Add-Ons compatibility is a must - this could prevent the Environment from starting at times. If there are no recent releases of the plugin that are compatible with the new JIRA Version, I'd recommend sorting out what's critical for the users - and what isn't, and based on that going ahead with the upgrade.

4) Communication with users is always vital - after upgrading the Staging Environment, users are the best tester. Users can use JIRA in ways that even JIRA Admin would at times miss out.  This is specially recommended when there are too many plugins in use. JIRA Admins are bound to miss one defect or another if it has been introduced with Upgrades. Hence, involve and inform users of Upgrade is vital.

5) Backups - Database Backup and XML backup of the environment is a must.

6) Customizations - JIRA Admin should always be aware of customizations that have been made to their JIRA Environment. Based on that information, Admins can restore back any customizations that have been replaced during Upgrades.

Community Manager
Community Managers are Atlassian Team members who specifically run and moderate Atlassian communities. Feel free to say hello!
September 17, 2018

Thanks @Bastian Stehmann and @Vickey Palzor Lepcha for sharing your upgrade tips! I agree - keeping a close eye on details like staging data, customizations, and add-ons is really key to the process. 


Log in or Sign up to comment
AUG Leaders

Atlassian Community Events