Upgrade checklist

Use this checklist as a guide to ensure you're set up for success for your Jira Software 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 latest 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.

Get your list of files with custom modifications

Have you modified files to customize your Jira? If you want to keep these changes, make sure you know which files have been modified. 

  • If you're on the latest version of the ASTS plugin, go to Jira administration  > Applications Plan your upgrade to see the list of files in which you introduced custom changes.

     If you've made changes to 

    - <jira-home-directory>/atlassian-jira/ directory
    - <jira-home-directory>/conf/server.xml
    - <jira-home-directory>/bin/setenv.sh

    we'll automatically transfer these changes to your upgraded Jira before you start it. However, if you've made changes to other files, you'll need to manually transfer them.

  • If you can't pull up the Plan your upgrade page, compile the list of files you've modified. For some suggestions regarding files that get modified most frequently, see here
For more info, see Pre-upgrade planning tool.



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. 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're 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're running a clustered or non-clustered Data Center, 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.


Re-apply any modifications and increase pool-max-size
If you've made changes any of the files copy them over to your upgraded instance. These changes might include:
  • customisations to xml configuration files (e.g so they can use load balancing)

  • custom icons (e.g replacing the Jira logo with their company logo)

  • custom email templates (similarly related to the branding thing)

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.

Which files did I change?

If you're unsure which files you might have modified, go to Jira administration  >Applications Plan your upgrade to see the list of files in which you introduced custom changes.

Alternatively, 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
What do I do with my changed files?

When you know which files have been modified, copy these modifications to the respective files in your upgraded Jira. Copy only the modified parts not the entire files!

If you're upgrading to Jira 8.6 and later and running the ATST version 1.20.0 or later, we will show you the files whose modifications have not been copied over on Jira startup. Then, you'll be able to copy the changes automatically.

You'll be prompted to restart Jira after copying is completed.

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

Any changes to dbconfig.xml require a restart.


Decide when to reindex

7.X TO 8.X UPGRADE Jira 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 haven't done it already)

If you're upgrading to Jira 8.6 and later and running the ATST version 1.20.0 or later, you can see a list the files whose modifications have not been copied over on Jira startup. Then, you can just select to copy the changes automatically.

Note that when checking for changes, we're only looking at the files/folders below:

- <jira-home-directory>/atlassian-jira/ directory
- <jira-home-directory>/conf/server.xml
- <jira-home-directory>/bin/setenv.sh

To automatically transfer the changes, the installer copy of the modified file needs to be the same as in the version you're upgrading to.

You'll be prompted to restart Jira after copying is completed.


Test the upgrade with users
  • Ask your Jira users if the upgrade works fine for them. This is super helpful if you're 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. 7.X TO 8.X UPGRADEBecause 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.

7.X TO 8.X UPGRADEDecide 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're 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 clustered or non-clustered Data Center, 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.

Re-apply any modifications
If you have made changes any of the files copy them over to your upgraded instance. These changes might include:
  • customisations to xml configuration files (e.g so they can use load balancing)

  • custom icons (e.g replacing the Jira logo with their company logo)

  • custom email templates (similarly related to the branding thing)

Which files did I change?

If you're unsure which files you might have modified, go to Jira administration  Applications Plan your upgrade to see the list of files in which you introduced custom changes.

Alternatively, 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
What do I do with my changed files?

When you know which files have been modified, copy these modifications to the respective files in your upgraded Jira. Copy only the modified parts not the entire files!

If you're upgrading to Jira 8.6 and later and running the ATST version 1.20.0 or later, we will show you the files whose modifications have not been copied over on Jira startup. Then, you'll be able to copy the changes automatically.

You'll be prompted to restart Jira after copying is completed.


7.X TO 8.X UPGRADEDecide 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 haven't done it already)

If you're upgrading to Jira 8.6 and later and running the ATST version 1.20.0 or later, you can see a list the files whose modifications have not been copied over on Jira startup. Then, you can just select to copy the changes automatically.

Note that when checking for changes, we're only looking at the files/folders below:

- <jira-home-directory>/atlassian-jira/ directory
- <jira-home-directory>/conf/server.xml
- <jira-home-directory>/bin/setenv.sh

To automatically transfer the changes, the installer copy of the modified file needs to be the same as in the version you're upgrading to.

You'll be prompted to restart Jira after copying is completed.


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 Data Center 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 Dec 1, 2023

Was this helpful?

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