Upgrade checklist

Use this checklist as a guide to ensure you are set up for success for your Jira Software Server upgrade. Keep in mind that every instance is unique, and this guide should be supplemented with tasks and customizations specific to your instance.

You can use this template and make additions to suit your Jira Software instance.

View checklist as a Trello board 

StageTaskNotes

Status/Comments

Research & decision

Decide which version to upgrade to

  • Use the Jira Software upgrade matrix to compare versions and select the version that suits your needs. Then go to upgrade notes to check the technical aspect of the upgrade.

    tip/resting Created with Sketch. Pro Tip: if you upgrade infrequently, a Long Term Support release might be the version for you.

Outline upgrade stakeholders (optional)
  • List roles, responsibilities, and contact info to keep the interested parties in the loop and be aware of all the dependencies.

Preparation & testing


Check maintenance status
  • You need to have a valid licence to upgrade Jira. Check and renew at my.atlassian.com.

Check supported platforms
  • It might happen that some platforms reached their end of life and we stopped supporting them. Check the Supported Platforms page for details.

Set up your testing environment
Run an instance health check
  • See if your instance is good to upgrade. Health check is embedded in the Support Tools Plugin. More details here.

Check the compatibility of your apps
  1. Check app compatibility with the Jira update check.
  2. JIRA 8.0 Because of major changes we've introduced in Jira 8.0, you need to disable all incompatible apps before the upgrade. We also recommend disabling the apps with the status:
    • Incompatible
    • Compatible if both upgraded
    • Unknown
  3. Upgrade your apps with the Compatible if upgraded status.

    See Incompatible apps.

Determine your optimal upgrade method

Choose a Jira upgrade method:

If you are starting from Jira 6.4 or earlier, you need to upgrade to Jira 7.x (for example: 7.13) first before you upgrade to 8.x.

tip/resting Created with Sketch. Pro Tip: Depending on your OS or whether you are running a DC or a standalone Jira Server, there might be some restrictions to the upgrade method you can choose. See Upgrade methods.

Do the upgrade

CLUSTER When you upgrade, you perform all the pre-upgrade steps, next you perform an upgrade and do the post-upgrade task on one node. Next you create a template and upgrade all other nodes. Only then can you make post-upgrade steps for the entire DC.


JIRA 8.0Decide when to reindex

Jira 8.0 will automatically remove the old incompatible index and start a full re-index on startup.  You might want to postpone reindexing to upgrade your apps first, as some apps will require an additional reindexing. For more information, see Disabling automatic reindexing.
Start Jira

Upgrade your appsNow you can upgrade the apps with the Compatible if both upgraded status.
Re-apply any modifications and increase pool-max-size

Test customizations in your testing environment prior to upgrading your production instance, because there is a chance that changes during the upgrade will make your Jira Software customizations unusable.

Details

If you're unsure which files you might have modified, take a look at the list of important files in the Jira installation directory.

Also, you might want to look in the logs for the Modifications section:

If you use the installer method, then the following parameters were migrated from your existing Jira Software installation:

  • TCP values in the server.xml file
  • Location of your Jira home directory in the Jira-application.properties file
  • The following values in the setenv.sh / setenv.bat file:
    • JVM_SUPPORT_RECOMMENDED_ARGS
    • JVM_MINIMUM_MEMORY
    • JVM_MAXIMUM_MEMORY
    • Jira_MAX_PERM_SIZE

All other customizations need to be reapplied manually. If you used the manual upgrade method, be sure to reapply all customizations manually (including those listed above). To do this, follow these steps:

  1. Stop your upgraded Jira instance.
  2. Reapply the customizations to the relevant files in the upgraded Jira installation directory.
  3. If you're upgrading from Jira 7.x to Jira 8.x we recommend changing the pool-max-size parameter to 40 in your dbconfig.xml before the upgrade. Leaving the default of 20 can sometimes lead to “ResultSet Closed” errors during re-indexing on 8.x. For information on implementing the change, see Tuning database connections

  4. Restart the upgraded Jira instance.

Test the upgrade with users
  • Ask your Jira users if the upgrade works fine for them. This is super helpful if you are passing a major version, ie. 8.0. Select a diverse sample group that utilizes different features of Jira Software.

Document learnings (optional)
  • Document the things you notices during the upgrade - that can help you with future upgrades.
  • Update timeline and stakeholders if necessary.

Create a timeline and communicate
  • Remember to book enough time for your upgrade. Add some buffer time, too.
  • Communicate the change to end users.

Preparation & execution



Check maintenance status
  • You need to have a valid licence to upgrade Jira. Check and renew at my.atlassian.com.

Check supported platforms
  • It might happen that some platforms reached their end of life and we stopped supporting them. Check the Supported Platforms page for details.

Run an instance health check
  • See if your instance is good to upgrade. Health check is embedded in the Support Tools Plugin. More details here.

Check the compatibility of apps
  1. Check app compatibility with the Jira update check.
  2. JIRA 8.0 Because of major changes we've introduced in Jira 8.0, you need to disable all incompatible apps before the upgrade. We also recommend disabling the apps with the status:
    • Incompatible
    • Compatible if both upgraded
    • Unknown
  3. Upgrade your apps with the Compatible if upgraded status.

    See Incompatible apps.

Back up your instance data
  • Use native database backup tools, unless you're changing some parts of your environment (e.g. database software), in which case you'll need to use a Jira's XML backup utility.
  • Check out a detailed breakdown of the two processes here

Back up your directories
  • Back up your installation and home directory. More details here.
    CLUSTER Remember to do the backup for all the nodes and to also back up the shared directory.

JIRA 8.0Decide when to reindex

Jira 8.0 will automatically remove the old incompatible index and start a full re-index on startup. You might want to postpone reindexing to upgrade your apps first, as some apps will require an additional reindexing. For more information, see Disabling automatic reindexing.


Execute upgrade in production environment

You have the following upgrade methods:

If you are starting from Jira 6.4 or earlier, you need to upgrade to Jira 7.x first before you upgrade to 8.x.

tip/resting Created with Sketch. Pro Tip: Depending on your OS or whether you are running a DC or a standalone Jira Server, there might be some restrictions to the upgrade method you can choose. See Upgrade methods.

CLUSTER When you upgrade, you perform all the pre-upgrade steps, next you perform an upgrade and do the post-upgrade task on one node. Next you create a template and upgrade all other nodes. Only then can you make post-upgrade steps for the entire DC.


Upgrade the database driver (if using Oracle or MySQL)

To start Jira successfully:

  • Download the latest JDBC driver (Oracle or MySQL)
  • Place it in <Jira-installation-directory>/lib.

JIRA 8.0Decide when to reindex

Jira 8.0 will automatically remove the old incompatible index and start a full re-index on startup.  You might want to postpone reindexing to upgrade your apps first, as some apps will require an additional reindexing. For more information, see Disabling automatic reindexing .
Start Jira

Upgrade your appsNow you can upgrade the apps with the Compatible if both upgraded status.
Re-apply any modifications

If you're unsure which files you might have modified, take a look at the list of important files in the Jira installation directory.

Also, you might want to look in the logs for the Modifications section:

If you use the installer method, then the following parameters were migrated from your existing Jira Software installation:

  • TCP values in the server.xml file
  • Location of your Jira home directory in the Jira-application.properties file
  • The following values in the setenv.sh / setenv.bat file:
    • JVM_SUPPORT_RECOMMENDED_ARGS
    • JVM_MINIMUM_MEMORY
    • JVM_MAXIMUM_MEMORY
    • Jira_MAX_PERM_SIZE

All other customizations need to be reapplied manually. If you used the manual upgrade method, be sure to reapply all customizations manually (including those listed above). To do this, follow these steps:

  1. Stop your upgraded Jira instance.
  2. Reapply the customizations to the relevant files in the upgraded Jira installation directory.
  3. Restart the upgraded Jira instance.

Post-upgradeTest the upgrade with users
  • Asking users if the upgrade works fine for them is super helpful.
  • Use the same sample group as the test upgrade
  • Resolve any issues before marking the upgrade as complete

Communicate to end users

Include major feature additions and contact information for questions


Complete an upgrade retrospective (optional)

Document what went well, what didn't, and what to change for next time. This will help your next upgrade run even smother.



Resources

Caught between a rock and a hard place? Here are a few resources to consult if you have questions. We recommend proceeding in this order: 

  • Browse or search the Jira Software documentation site and the Jira Software Server Knowledge Base. (Be sure to select the appropriate version in the dropdown.)
  • Search our Atlassian Community site for articles and discussions pertaining to your topic. Or, ask a question to tap into Community experts both inside and outside of Atlassian. 
  • Create an issue at our support site so that our support engineers can assist you.
  • If you purchased your license through an authorized Solution Partner, consult them to learn more about troubleshooting your instance.
  • Looking for more assistance? We also offer Premier Support, which includes 24 x 7 support availability, health checks, dedicated senior support engineers, and more. Check out our Premium Support offerings for more information.


Last modified on Jun 26, 2020

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.