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.
| Stage | Task | Notes | Status/Comments |
|---|---|---|---|
| Research & decision | Decide which version to upgrade to |
| |
| Outline upgrade stakeholders (optional) |
| ||
| Preparation & testing | Check maintenance status |
| |
| 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.
| ||
| Check supported platforms |
| ||
| Set up your testing environment |
| ||
| Run an instance health check |
| ||
| Check the compatibility of your 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.
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:
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 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:
If you're upgrading from Jira 7.x to Jira 8.x we recommend changing the 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 apps | Now 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 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 |
| ||
| Document learnings (optional) |
| ||
| Create a timeline and communicate |
| ||
| Preparation & execution | Check maintenance status |
| |
| Check supported platforms |
| ||
| Run an instance health check |
| ||
| Check the compatibility of apps |
| ||
| Back up your instance data |
| ||
| Back up your directories |
| ||
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.
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: | ||
| Re-apply any modifications | If you have made changes any of the files copy them over to your upgraded instance. These changes might include:
Which files did I change?
If you're unsure which files you might have modified, go to Jira administration 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:
| ||
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 apps | Now 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 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-upgrade | Test the upgrade with users |
| |
| 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.
All good?