Stash upgrade guide

This page describes how to update your Stash installation to the latest version. We strongly recommend that you update Stash by performing the steps below.

Note that:

• This update process does not perform an in-place upgrade, but installs the new version of Stash into a fresh installation directory. The new Stash uses your existing Stash home directory and external database.
• You can update from any previous version to the latest version of Stash.
• For production environments we recommend that you test the Stash update on a QA server before deploying to production.

1. Review the upgrade notes

There are specific upgrade notes further down this page for each version of Stash. 

You should read the relevant sections for each version between your current version of Stash and the version you are upgrading to.

Note that you can update from any previous version to the latest version of Stash.

2. Back up your Stash data

See Data recovery and backups for more information.

3. Stop Stash

See Starting and stopping Stash. For Stash Data Center instances, repeat the process on every cluster node. 

4. Install Stash

This update process does not perform an in-place upgrade, but installs the new version of Stash into a fresh installation directory. The new Stash uses your existing Stash home directory and external database.

Check that you have all the system requirements for the new version of Stash, including Perl, to avoid any trouble. 

See also the End of support announcements for Stash.

You can install Stash by either:

• Using the Stash installer, the recommended approach.
• Installing Stash from an archive file.

For Stash Data Center instances, repeat the update process for every cluster node. 

Use the Stash installer to update your Stash installation (Recommended)

Download the Stash installer from the Atlassian download site. You can run the installer in GUI, console or unattended modes.

On Linux, you need to set the executable flag on the installer file before running it: 

chmod +x atlassian-stash-x.x.x-x64.bin

At the 'Welcome' step, choose the Upgrade an existing Stash instance option:

At the 'Select Stash Home' step, browse to your existing Stash home directory (as defined by the STASH_HOME environment variable – see Stash home directory):

Stash 3.5 and later versions no longer allow the Stash home directory  to be the same directory as, or a subdirectory of, the Stash installation directory. The Stash home directory, as defined by the STASH_HOME  environment variable, must be in a separate location – otherwise Stash will fail on startup.

If upgrading from a previous version of Stash where the Stash home directory is owned by a local user, the ownership of all files will be updated to atlstash . Please allow sufficient time for the installer to complete this process (it could take up to 30 minutes) .

Proceed with the remaining installer steps.

Use an archive file to update your Stash installation

You should only need to use an archive file to update Stash if the Stash installer, which is the recommended approach, is not suitable for your situation.

Follow the instructions at Installing Stash from an archive.

Note that on Windows, Stash 3.5 and later versions will refuse to start if the installation path contains spaces, when Stash is installed from an archive file. The Stash installer prevents you from creating such a path. 

5. Update any custom configurations

If you have made custom changes to the configuration of your existing Stash installation you will have to make those changes for the new installation as well. For example:

• You may have made changes to the port, context path, or the access protocol (in <Stash installation directory>/conf/server.xml).
• You may be running Stash behind a proxy and have modified the Connector element (in <Stash installation directory>/conf/server.xml).
• You may be using 64-bit libraries on Windows instead of the out-of-the-box 32-bit libraries (bin/tomcat7.exe, bin/tcnative-1.dll).
• If you are using MySQL, you'll need to reinstall the driver in the new installation, or copy the previous driver from the old <Stash installation directory>/lib to the new <Stash home directory>/lib.

Do not simply copy the configuration files from your existing <Stash installation directory> to your new <Stash home directory>/shared directory. Carefully review the differences between your customized version and the default version and re-apply your custom changes to the new configuration files to prevent overwriting configuration changes between different versions of Stash.

For Stash Data Center, using Stash 3.8, or later, the single server.xml file in the <Stash home directory> /shared directory replaces all the copies of server.xml located in the  <Stash installation directory>/conf directories of the cluster nodes using previous versions of Stash.

6. Start Stash

If you installed Stash using the installer, Stash will already have been started by the installer.

If you installed Stash manually from an archive file then see Starting and stopping Stash. For Stash Data Center instances, repeat the process on every cluster node. 

Either way, note that the database schema migration task that runs when Stash is started after an update can take a while, especially if the update has skipped a few releases (for example, upgrading from Stash 2.2 to 2.7). Stash should never be interrupted while this is happening, even if Stash appears to have hung – allow the server to either come up, or fail to come up (when it will provide an explanation of what went wrong).

Home directory migration

When you update from Stash 3.1 or older to Stash 3.2 or later, an update task migrates directories in your Stash home directory to new locations. This is irreversible – once you update to Stash 3.2 or later you can not revert to Stash 3.1 or earlier, because of changes to the Stash home directory format.

For most installations, Stash is able to perform these moves automatically and transparently. However, in the rare instance where Stash can't perform the update automatically, please refer to Upgrading your Stash home directory for Stash 3.2 manually.

Rollback

If necessary, rolling back an update can only be performed by restoring a backup of both the Stash home directory and the Stash database – rolling back requires a consistent home directory and database. You can then reinstall the previous version of Stash to the <Stash installation directory>.

Version-specific update notes

This section provides specific update notes for each version of Stash. These notes supplement the primary update guide above.

You should read the relevant sections for each version between your current version of Stash and the version you are upgrading to.

Stash 3.8 update notes

Please also see:

• the general Upgrade steps section above.
• the Stash 3.8 release notes.
• the Stash Supported platforms page. Note that Stash 3.8 does not support Git 2.0.2 or 2.0.3.
• the End of support announcements for Stash. Note that, in particular, Stash 4.0 will not support Internet Explorer 9, Java 7, nor versions of Git earlier than 1.8 on the server.

Have you made customizations to Tomcat's server.xml file?

For Stash 3.8 (and future versions) the server.xml file is now located in the <stash home directory>/shared directory. The benefit of this move is that your customizations to server.xml (such as those described in step 5) will not have to be redone for future upgrades.

 You do still need to update your custom configurations in shared/server.xml  for the upgrade to Stash 3.8, as described in step 5.

Deprecation of HighlightJS for syntax highlighting

The highlighting engine was changed in Stash 3.5 from HighlightJS to CodeMirror. The use of HighlightJS for syntax highlighting in Stash is now deprecated, and will be removed in Stash 4.0. See Syntax highlight changes for information about how to migrate any custom mappings for HighlightJS that you may have made.

Known issues

Stash 3.7 update notes

Please also see:

• the general Upgrade steps section above.
• the Stash 3.7 release notes.
• the Stash Supported platforms page. Note that Stash 3.7 does not support Git 2.0.2 or 2.0.3.
• the End of support announcements for Stash. Note that, in particular, Stash 4.0 will not support Internet Explorer 9, Java 7, nor versions of Git earlier than 1.8 on the server.

Do you use JIRA 6.4?

Deprecation of HighlightJS for syntax highlighting

The highlighting engine was changed in Stash 3.5 from HighlightJS to CodeMirror. The use of HighlightJS for syntax highlighting in Stash is now deprecated, and will be removed in Stash 4.0. See Syntax highlight changes for information about how to migrate any custom mappings for HighlightJS that you may have made.

Known issues

Stash 3.6 update notes

Please also see:

• the general update steps section above.
• the Stash 3.6 release notes.
• the Stash Supported platforms page. Note that Stash 3.6 does not support Git 2.0.2 or 2.0.3.
• the End of support announcements for Stash. Note that, in particular, Stash 4.0 will not support Internet Explorer 9, Java 7, nor versions of Git earlier than 1.8 on the server.

Secure email notifications

Stash 3.6 now:

• Allows you to require STARTTLS support on the mail server when using SMTP – if it is not supported, mail is not sent. 
• Supports SMTPS (where the whole protocol conversation uses SSL/TLS).

See Setting up your mail server for more information.

Note that if you use either SMTP with STARTTLS or SMTPS and connect to a self-signed mail server you may need to import the server's certificate and set up a custom cacerts file for Stash (just as you do for any outbound SSL/TLS connection to a self-signed server). See this  Stash knowledge base article for information about how to do that.

Deprecation of HighlightJS for syntax highlighting

The highlighting engine was changed in Stash 3.5 from HighlightJS to CodeMirror. The use of HighlightJS for syntax highlighting in Stash is now deprecated, and will be removed in Stash 4.0. See Syntax highlight changes for information about how to migrate any custom mappings for HighlightJS that you may have made.

Known issues

Stash 3.5 update notes

Please also see:

• the general update steps section above.
• the Stash 3.5 release notes.
• the Stash Supported platforms page. Note that Stash 3.5 does not support Git 2.0.2 or 2.0.3.
• the End of support announcements for Stash. Note that, in particular, Stash 4.0 will not support Java 7, nor versions of Git earlier than 1.8 on the server.

Stash home directory location

Stash 3.5 and later versions no longer allow the Stash home directory to be the same directory as, or a subdirectory of, the Stash installation directory. The Stash home directory, as defined by the STASH_HOME environment variable, must be in a separate location – Stash will fail on startup otherwise.

Deprecation of HighlightJS for syntax highlighting

The highlighting engine in Stash has been changed from HighlightJS to CodeMirror. The use of HighlightJS for syntax highlighting in Stash is now deprecated, and will be removed in Stash 4.0. See Syntax highlight changes for information about how to migrate any custom mappings for HighlightJS that you may have made.

Known issues

Stash 3.4 update notes

Please also see:

• the general update steps section above.
• the Stash 3.4 release notes.
• the Stash Supported platforms page. Note that Stash 3.4 does not support Git 2.0.2 or 2.0.3.
• the End of support announcements for Stash.

Changed group membership aggregation with multiple user directories

Stash 3.4 uses new schemes to determine the effective group memberships when Stash is connected to multiple user directories, and duplicate user names and group names are used across those directories. The new schemes are: 

• 'aggregating membership'
• 'non-aggregating membership'.

These group membership schemes are only used to determine authorisation. Authentication is determined on the basis of the group mappings in each directory.

See Effective memberships with multiple directories in the Crowd documentation for more information.

When you update to Stash 3.4, an update task will apply one of those schemes as follows:

Aggregating membership will be applied to your instance:

• • If there is only one active directory.
  • If there are multiple active directories but only a single directory applies group memberships to any particular user.
  • For example, if directory-1 contains user-a in group-x, and directory-2 contains user-b in group-y, then Stash 3.4 will apply aggregating membership, and permissions will not be affected.

Non-aggregating membership will be applied to your instance:

• • If there are multiple active directories and more than one directory applies group memberships to at least one user.
  • For example, if directory-1 contains user-a in group-x, and directory-2 contains user-a in group-y, then Stash 3.4 will apply non-aggregating membership. If group-y has admin provileges then user-a would have their privileges escalated in this case if aggregating membership was applied instead when upgrading to Stash 3.4.

Any changes made by the update task will be logged.

A Stash admin can change the membership scheme used by Stash using the following commands:

• To change to aggregating membership, substitute your own values for <username>, <password> and <base-url> in this command:

  curl -H 'Content-type: application/json' -X PUT -d '{"membershipAggregationEnabled":true}' -u <username>:<password> <base-url>/rest/crowd/latest/application 

• To change to non-aggregating membership, substitute your own values for <username>, <password> and <base-url> in this command:

  curl -H 'Content-type: application/json' -X PUT -d '{"membershipAggregationEnabled":false}' -u <username>:<password> <base-url>/rest/crowd/latest/application 

Please note that changing the aggregation scheme can affect the authorisation permissions for your Stash users, and how update operations are performed. Read more about using Stash with multiple use directories.

Known issues

Stash 3.3 update notes

Please also see:

• the general update steps section above.
• the Stash 3.3 release notes.
• the Stash Supported platforms page. Note that Stash 3.3 does not support Git 2.0.2 or 2.0.3.
• the End of support announcements for Stash.

Known issues

Stash 3.2 update notes

Please also see:

• the general update steps section above.
• the Stash 3.2 release notes.
• the Stash Supported platforms page.
• the End of support announcements for Stash.

Note that:

• Stash 3.2 does not support Git 2.0.2 or 2.0.3.

Home directory migration

When you update to Stash 3.2 or later, an update task migrates directories in your Stash home directory to new locations. This is irreversible – once you update to Stash 3.2 or later you can not revert to Stash 3.1 or earlier, because of changes to the Stash home directory format.

For most installations, Stash 3.2 is able to perform these moves automatically and transparently. However, in the rare instance where Stash 3.2 can't perform the update automatically, please refer to Upgrading your Stash home directory for Stash 3.2 manually.

Undocumented home directory overrides are no longer supported

In Stash 3.2 only the  tmp  subfolder can be overridden in this way. Attempting to override the others will fail on startup. For more information, please see  Stash fails to start - UnsupportedDirectoryOverrideException . 

Stash analytics

Stash 3.2, and later, collects user event data, unless this is disabled by an administrator. You will see outgoing network traffic to amazonaws.com. See Collecting analytics for Stash.

Known issues

Stash 3.1 update notes

Please also see:

• the general update steps section above.
• the Stash 3.1 release notes.
• the Stash Supported platforms page.

Note that:

• Stash does not support Git 2.0.2 or 2.0.3.

Known issues

Stash 3.0 update notes

Please also see:

• the general update steps section above.
• the Stash 3.0 release notes.
• the Stash Supported platforms page.

Note that:

• Stash now has installers for the Linux, Mac OS X and Windows platforms.
• Stash no longer supports Internet Explorer  8, as previoiusly announced.
• Stash does not support the Apache HTTP Server mod_auth_basic module.
• Stash does not support Git 2.0.2 or 2.0.3.

Stash add-on incompatibilities

Unless they have been updated to work with Stash 3.0, existing Stash add-ons (or plugins) that use the API interfaces that have been removed in Stash 3.0 will not work.

Fresh installs of Stash 3.0 shouldn't encounter any problems. The Stash 'Manage add-ons' page (in the admin area) should only display add-ons from the Marketplace that have been marked as compatible with Stash 3.0. Incompatible add-ons won't be available in the list. 

However, if you are upgrading from Stash 2.x to Stash 3.0, you should be aware that some existing installed add-ons may be incompatible with Stash 3.0. After upgrading, you should go to Admin > Manage add-ons, look for messages of this form, and follow the advice to update:

If no newer version is available, the add-on must be disabled. 

Custom add-ons

Please note that your custom locally-developed plugins may be affected by the API removals in Stash 3.0. You will need to update your custom plugins if you want those to work with Stash 3.0. See the Stash API changelog for details of the deprecated APIs.

Third-party add-ons

You'll need to check on Atlassian Marketplace for the compatibility status of any 3rd-party add-ons that you use.

Third-party add-on developers have been given an Early Access Program (EAP) build of Stash 3.0 in advance of release, and many have already updated their add-ons to be compatible. Add-ons must be explicitly marked by the publisher as compatible with Stash 3.0 for them to appear in 'Manage add-ons' page in Stash. This is NOT automatic as was the case with previous minor releases such as 2.10 and 2.11. Atlassian can not support issues involving third party Add-ons that are incompatible with Stash 3.0; such support cases must be directed to the third-party publisher of the add-on. See Managing add-ons.

Atlassian add-ons

All of the Atlassian add-ons for Stash that are available from the Atlassian Marketplace have been updated to be compatible with Stash 3.0. If you use any of these in your Stash installation you'll need to update them to the Stash 3.0 compatible version.

Known issues

Stash 2.12 update notes

Please also see:

• the update steps section above.
• the End of support announcements for Stash. In particular, note that support for Java 6 is deprecated. Stash 3.0+ will require Java 7.
• the Stash 2.12 release notes.

Note that:

• Stash does not yet support Java 8.
• Stash 2.12 does not support Git 1.8.4.3
• Stash does not support the Apache HTTP Server mod_auth_basic module. 

See Supported platforms.

Known issues

Stash 2.11 update notes

Please also see:

• the update steps section above.
• the End of support announcements for Stash.
• the Stash 2.11 release notes.

Note that Stash does not support Git 1.8.4.3, nor does Stash support Java 8 yet. See Supported platforms.

Known issues

Stash 2.10 update notes

Please also see:

• the update steps section above.
• the End of support announcements for Stash.
• the Stash 2.10 release notes.

Note that Stash does not support Git 1.8.4.3. See Supported platforms.

Known issues

Stash 2.9 update notes

Please also see:

• the update steps section above.
• the End of support announcements for Stash.
• the Stash 2.9 release notes.

Note that Stash does not support Git 1.8.4.3. See Supported platforms.

Pull Request Ref Optimization

When you first start Stash after upgrading to Stash 2.9 a repository update task runs that optimizes the pull request refs for all repositories managed by Stash. It's important that you do not interrupt this update process. You can track the progress of this in the Stash logs. See  STASH-3469 - Getting issue details... STATUS .

Backup Client Update Required

Version 1.0.3 of the Stash Backup Client is required to back up Stash 2.9.

Known issues

Stash 2.8 update notes

Please also see:

• the update steps section above.
• the End of support announcements for Stash.
• the Stash 2.8 release notes.

Known issues

Stash 2.7 update notes

Please also see:

• the update steps section above.
• the End of support announcements for Stash.

Repository System Information Plugin is now deprecated

The functionality of the repository system information plugin has now been moved into core Stash. The plugin will still work for Stash 2.x versions but is redundant as of Stash 2.7.

MySQL default isolation level

Stash 2.7.x uses READ_COMMITTED instead of the MySQL default isolation level (REPEATABLE_READ). This can result in exceptions when installing or upgrading to 2.7.x, if binary logging is enabled in your MySQL server. More details and a fix can be found in this KB article.

Known issues

Stash 2.6 update notes

Please also see:

• the update steps section above.
• the End of support announcements for Stash.

Known issues

Stash 2.5 update notes

Please also see:

• the update steps section above.
• the End of support announcements for Stash.

Known issues

Limited support for JIRA 4.4.x and earlier

JIRA 4.3+ allows for showing commits associated with issues in JIRA. However, viewing issues within Stash is not supported for JIRA 4.4.x and earlier. See JIRA compatibility for details. 

Stash 2.4 update notes

Please also see:

• the update steps section above.
• the End of support announcements for Stash.

Known issues

Stash 2.3 update notes

Please also see the update steps section above.

When upgrading to Stash 2.3 you also need to update the SCM Cache plugin, due to recent Stash API changes.

Known issues

Stash 2.2 update notes

Please see the update steps section above.

Known issues

Stash 2.1 update notes

Please also see the update steps section above.

Known issues

Install location for third-party libraries

As of Stash 2.1 you can install third-party libraries and jar files, such as the MySQL JDBC driver, into <Stash home directory>/lib. This has the advantage that files in this location are not overwritten, and lost, when you update Stash.

Microsoft SQL Server JDBC driver

Stash 2.1 now uses the Microsoft SQL Server JDBC driver to access Microsoft SQL Server, instead of using the jTDS driver. In most cases, Stash will automatically swap to using the Microsoft driver on update and no configuration is required.

If Stash was configured to use Microsoft SQL Server by manually entering a JDBC URL, please refer to this guide.

Stash 2.0 update notes

This section provides specific notes for upgrading to Stash 2.0. See also the update steps section above.

Tomcat

For Stash 2.0, Tomcat has been updated from version 6 to 7. As part of that update, the server.xml file has changed. If you have customised server.xml (for example, for port, path or hostname), you can not simply copy your own version across to the updated Stash; you must reapply your customisations to the server.xml file for the new version of Stash.

If you were running Stash as a Windows service and are upgrading from 1.x to 2.x you will need to reinstall the Stash service to make it use Tomcat 7.

To uninstall the Stash service you need to execute following commands from <STASH DISTRIBUTION DIR>\bin:

> net stop <service name>
> service.bat uninstall <service name>

You can call this command without the service name if you installed the Stash service with a default name.

After the service is uninstalled you can proceed with the update steps and Running Stash as a Windows service instructions to configure Stash 2.x running as a service.

Perl

Stash 2.0 requires Perl for its branch permission functionality. If Perl is unavailable, Stash 2.0 will not start.

On Windows machines, Perl will only have been installed by the Git installer if the correct install option was chosen. See Installing and upgrading Git.

Existing Git hooks

In order to support Branch Permissions, Stash 2.0 moves existing hooks in the pre-receive and post-receive folders under <STASH_HOME>/data/repositories/NNNN/hooks (where NNN is the internal repository id)  to .../hooks/pre-receive.d/10_custom or .../hooks/post-receive.d/10_custom. Consequently, custom hooks that use relative path names (e.g. "./foo.sh" or "../dir/foo.sh") will be broken by the update to Stash 2.0.

Deprecation of Internet Explorer 8

Support for Internet Explorer 8 is deprecated from the release of Stash 2.0. The official end-of-support date is yet to be determined. See Supported platforms for details.

Known issues

Checking for known issues and troubleshooting

If something is not working correctly after you have completed the steps above to update your Stash installation, please check for known Stash issues and try troubleshooting your update as described below:

• Check for known issues. Known issues can be seen in the STASH project on our issue tracker.
• Stash Knowledge Base. Sometimes we find out about a problem with the latest version of Stash after we have released the software. In such cases we publish information in the Stash Knowledge Base.
• If you encounter a problem during the update and cannot solve it, please create a support ticket and one of our support engineers will help you.