Jira Software 10.0.x upgrade notes
Here are some important notes on upgrading to Jira Software 10.0.x. For details of the new features and improvements in this release, see the Jira Software 10.0 release notes.
Platform releases allow us to incorporate multiple significant changes (often called “breaking changes”) that aren't compatible with previous versions. These changes establish a strong foundation for more extensive development in future releases.
To increase security and performance, we’ve made changes in our core architecture that require apps to bundle their libraries. We’re collaborating with our Marketplace partners on these changes, however, some apps may not be immediately compatible with the new platform upon release and cause product experience breaks. We recommend that you review your apps before upgrading to avoid service disruptions for your organization.
To check app compatibility, visit Checking app compatibility with application updates or the Atlassian Marketplace to see if your app hosting is compatible with your product version.
Skip to
- Front-end API changes
- OpenAPI standard for REST API documentation
- Removal of previously deprecated feature flags
- Breaking changes to the Java API
- Breaking changes to the REST API
- Removal of dependencies
- Removal of binary installers
- Jira Software and Jira Core dialogs migrated to AUI Dialog 2
- Application Links compatibility
- Velocity path traversal prevention and allowlisting
- Updates to database schema
- Removal of the jira-func-tests-legacy module
- Disabling the runtime JavaServer Pages compilation
- Custom JSPs are blocked unless loaded by an action
- Unbundling of atlassian-frontend-runtime-plugin
- Deprecation of jquery-migrate 1.x
- Centralized dependency management
- Changes to supported platforms
- App developers
- Known issues
- Upgrade procedure
Front-end API changes
This release brings an improved and updated Code sharing section of the Jira Data Center front-end API. We’ve introduced the following changes:
Inclusion of Jira-specific API modules, such as requested Jira Events.
Extensions and updates to common libraries.
Introduction to particular versioning of common libraries and alias module type.
Annotations to modules on the UPM level and better descriptions in the code.
Regular modules for the common libraries are versioned up to the minor version (x.y), for example, under the jira-frontend-api:react-18.3 web-resource Jira provides React 18.3.1, as of now. The patch version (aka bug fix) can be changed at any time, for example, the same web-resource can provide React 18.3.2 in the future.
The alias modules are versioned up to the major version (x), for example, under the jira-frontend-api:react-18 web-resource Jira provides React 18.3.1, as of now. The minor version can be changed at any time, for example, the same web-resource can provide React 18.4.0 in the future.
OpenAPI standard for REST API documentation
REST API documentation for Jira Core and Jira Software is now available in an OpenAPI standard with a refreshed graphical form. This is the first time REST API documentation for Jira Core and Jira Software is no longer split. What’s more, we’ve reviewed and updated the documentation content. Get started with REST API documentation for Jira
Removal of previously deprecated feature flags
In this release, we’ve removed the following feature flags:
com.atlassian.jira.agile.darkfeature.burnupchartoptimistic.transitionscom.atlassian.jira.advanced.audit.logvelocity.chart.uijira.quick.searchcom.atlassian.jira.custom.csv.escaperatlassian.cdn.static.assetsjira.users.and.roles.page.in.react
All features previously hidden behind those feature flags were enabled by default.
Breaking changes to the Java API
In this release, we've removed several deprecated methods and classes. Additionally, we’ve made adjustments to a group of methods which involved modifying the signatures and return types.
Breaking changes to the REST API
In this release, we’ve removed a set of REST API endpoints that have been deprecated since Jira Software 9.x.
Removal of dependencies
In this release, we’ve removed access to a number of dependencies.
Removal of binary installers
Starting from Jira 10.0, the .bin and .exe installers will no longer be available. You can still install Jira using the .zip and .tar.gz distributions.
Because of this change, Java is no longer bundled with Jira. Install Java manually
Jira Software and Jira Core dialogs migrated to AUI Dialog 2
This is still a work in progress. You can expect to see the full removal of AUI Dialog 1 from the Jira codebase by the upcoming LTS release.
Jira Software and Jira Core currently stand with significant majority of the components migrated to use AUI Dialog 2. AUI Dialog 1 will be removed from Jira completely by the upcoming LTS release. If your app uses that component, make sure to migrate to AUI Dialog 2.
Application Links compatibility
Starting from Jira 10.0, Application Links are only backward-compatible with products that have integrated a particular bug fix addressing incorrect Application Links version parsing. To enable Application Links to function properly, make sure to upgrade any other Atlassian products to a minimum supported version:
Jira Software | Jira Service Management | Confluence | Bitbucket | Bamboo | Crowd | Fisheye and Crucible |
|---|---|---|---|---|---|---|
|
|
|
|
|
|
|
Velocity path traversal prevention and allowlisting
We've upgraded Velocity to the Atlassian fork to implement path traversal prevention and allowlisting. The path traversal mechanism will escape any method call which contains parameter with path traversal symbols like ../. The method call will appear as a string on the front-end side.
Velocity template method invocations are now restricted to an allowlist. Unauthorized invocations will trigger a log warning and will be blocked to mitigate Server-Side Template Injection (SSTI) vulnerabilities. The global method allowlists encompass JDK and Atlassian class methods. Apps have the option to define their own allowlist using the module descriptor which will complement the global allowlist. We recommend that apps only expose immutable Data Transfer Objects (DTOs) and refrain from invoking application services or beans from templates.
Furthermore, all Velocity template files residing on the file system must be both allowlisted and of an allowlisted file type. This serves as a basic defense against attacks that combine file system access with a request to achieve remote code execution.
For now, the Velocity method allowlist is in debug mode so that app developers can adjust to this mechanism and for us to complete the main allowlist and minimize the risk of issues. The debug mode will be disabled at the earliest in the upcoming LTS.
Updates to database schema
We’ve updated the created column in the changegroup, jiraissue, and jiraaction tables to support millisecond precision. This change affects Oracle and MySQL databases only. No action is required—the schema will be automatically migrated upon restart.
Removal of the jira-func-tests-legacy module
We’ve removed the deprecated com.atlassian.jira:jira-func-tests-legacy module. Migrate your code from BaseJIRAWebTest (JUnit 3) to FuncTestCase (JUnit 4+).
Disabling the runtime JavaServer Pages compilation
JavaServer Pages (JSP) runtime compilation will be disabled in Jira Software 10.0. JSP files added to the Tomcat directory that aren't shipped with the product won’t be served. Furthermore, no modifications to the JSP files will be reflected. We recommend using Soy or Velocity templates instead.
Custom JSPs are blocked unless loaded by an action
We’ve blocked direct requests to JSP files. JSP files can now be only loaded when requested by an action.
Unbundling of atlassian-frontend-runtime-plugin
We’ve unbundled the atlassian-frontend-runtime-plugin provided common polyfills and the regenerator-runtime web resource. Since none of the supported browsers need these polyfills any longer and the plugin has been deprecated since Jira Software 9.2.0, we’ve removed it in Jira Software 10.0.
If your code is still using any web resources from this plugin, the following warnings may appear in your Jira logs:
This webresource is empty! All supported browsers no longer need these polyfills. Please remove your dependency on the "atlassian-frontend-runtime-plugin".
or
This webresource is deprecated and will soon be removed! All supported browsers no longer need the runtime. Please rebuild your sources without expecting the "regenerator-runtime" to be available.
The former babel-polyfill, core-js, custom-elements-v1, fetch, and focus-visible were already empty web resources, while the regenerator-runtime was still provided.
Deprecation of jquery-migrate 1.x
We’re upgrading jQuery and as part of that effort, we’ve deprecated jquery-migrate 1.x in Jira Software 10.0 and removed it from the superbatch Web Resource.
While jquery-migrate can still be loaded using certain Web Resource Keys (such as com.atlassian.plugins.jquery:jquery or com.atlassian.plugins.jquery:jquery-migrate), we advise against this.
For more information on the deprecation of jquery-migrate 1.x, visit the jQuery upgrade guide. For queries about jquery-migrate 1.x warnings, refer to jQuery migrate warnings. For future jQuery updates, refer to the 3.0 and 3.5 upgrade guides.
Centralized dependency management
Centralized dependency management in Jira Software 10 introduces a set of Maven POM files known as a Bill of Materials (BOM) which list the dependencies available to third-party apps.
This system aims to streamline responding to security threats and enhance efficiency of developing for Jira by ensuring that dependencies are uniform and up to date. This approach minimizes runtime errors such as NoSuchMethodException and allows for quicker responses to security vulnerabilities within these dependencies.
Changes to supported platforms
See what changes have been made to supported platforms in this Jira release. For more details, check out Supported platforms.
End-of-support announcements
We’ve removed support for:
.binand.exebinary installers- H2 database engine
- Java 8
- Java 11
We’ve unbundled:
Java (due to the binary installers removal)
App developers
For any important changes regarding apps, check out the Jira changelog.
FAQ for app developers
Based on your feedback from the Developer Community announcement of Jira Software 10.0, we’ve prepared a list of frequently asked questions.
Known issues
Redirect behavior of Stronger Defaults
To optimize the user experience requests are redirected (HTTP 302) to the login page when a security clearance requirement isn't met. This doesn’t apply to REST endpoints as they're intended for machines and programmatic use cases. For those, REST requests are rejected (HTTP 401/403). However, if your code is making a call to a non-REST endpoint, you need to handle the redirection case. Otherwise, your code can interpret the login page as the expected data and throw a parsing error.
We’re planning to improve this behavior in a future release by examining the Accept header before deciding whether to redirect or reject a request.
Automation for Jira 9.0.1 upgrade
If at some point you’ve used Automation for Jira version 9.0.1 and try to upgrade from Jira 8.20.x or later to Jira 10.0, you might experience issues around automation rules (such as not being allowed to enable, disable, or publish automation rules). Learn more about this issue
To fix this issue, you need to run the relevant SQL scripts manually in the Jira database:
- Stop the Jira application.
- Back up the database.
- Download the relevant script file for the type of database used by the Jira application as per step 5 in Upgrading to Automation for Jira 7.3.
- Run the script on the Jira database.
- Start the Jira application.
Important notice for MSSQL users
When upgrading to Jira 10.0.1, you'll experience an error that prevents Jira from starting. This issue is already fixed in Jira 10.1.1, that's why we recommend skipping 10.0.1 and upgrading directly to a newer Jira version.
The issue is related to a change in the default value of the encrypt connection parameter in the JDBC driver for MSSQL:
- Previous driver version (9.2.1): The default value for the
encryptparameter wasfalse. - Driver version in Jira 10.0.1 (12.6.3.jre11): The default value for the
encryptparameter is nowtrue.
Resolution
To resolve this issue, you need to explicitly set the encrypt parameter to false in your database connection string. Update the dbconfig.xml file as follows:
- Open the
dbconfig.xmlfile located in your Jira home directory. - Locate the connection string for your MSSQL database.
- Modify the connection string to include the parameter encrypt=false.
Example:<url>jdbc:sqlserver://your-database-server:1433;databaseName=your-database-name;encrypt=false;</url> - Save the changes and restart your Jira instance.
By following these steps, Jira should start without issues after the upgrade. We recommend removing the additional parameter after upgrading to a newer Jira version to keep the dbconfig.xml file clean.
Upgrade procedure
Before you upgrade, check app compatibility by visiting Checking app compatibility with application updates or the Atlassian Marketplace to see if your app hosting is compatible with your product version.
Upgrading from Jira version 9.x.x?
- See Upgrading Jira applications for complete upgrade procedures, including all available upgrade methods and pre-upgrade steps.
- For a more tailored upgrade, go to Jira administration, then Applications, then Plan your upgrade. We’ll recommend a version to upgrade to, run pre-upgrade checks, and provide you with a custom upgrade guide with step-by-step instructions.