Stash Latest (2.12) : Stash upgrade guide

Created and last modified by pwatson on Apr 02, 2014

This page describes how to upgrade Stash from a previous version.

  • For the latest and greatest Stash release, see Releases.

For production environments we recommend that you test the Stash upgrade on a QA server before deploying to production.

Please also read:

On this page:

Upgrade steps

This section provides general instructions for upgrading Stash. See also the specific notes on this page for the version of Stash you are upgrading to. We strongly recommend that you upgrade Stash by following these steps:

1. Stop Stash!

To stop Stash, change directory in a terminal or command prompt to the <Stash installation directory> and run:

  • Windows:

    bin\stop-stash.bat

  • Linux and Mac:

    bin/stop-stash.sh

2. Back up your Stash data!

Back up the Stash home directory. This is where your Stash data is stored. The home directory location is defined:

  • On Windows: by the STASH_HOME environment variable, or by the STASH_HOME line of <Stash installation directory>/bin/setenv.bat.
  • On Linux and Mac: by the STASH_HOME line of <Stash installation directory>/bin/setenv.sh.

If you are using an external database, back up this database. Follow the directions provided by the database vendor to do this.

See Data recovery and backups for more information.

3. Download and install Stash as usual

Download Stash from the Atlassian download site and unpack the archive file to a suitable location.

  • Note that you should not simply copy the unpacked Stash directory over an existing Stash directory. Copying a new Stash directory over the existing one is not supported – that will always corrupt the system. This is because each version of Stash includes versioned jar files, such as stash-model-2.4.1.jar. If you copy these, you end up with multiple versions of Stash's jar files in the classpath, which leads to runtime corruption.

Update the value of STASH_HOME in the new Stash installation directory to point to your existing Stash home directory (but note that if you use a STASH_HOME environment variable to specify the home directory location then no change is required):

  • On Windows, update the home directory location as defined by the STASH_HOME line of the new <Stash installation directory>/bin/setenv.bat. 
  • On Linux and Mac, update the home directory location as defined by the STASH_HOME line of the new <Stash installation directory>/bin/setenv.sh.

If you made custom changes to the configuration of your existing Stash installation

Icon

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

  • Changes to port, context path, and/or access protocol (conf/server.xml)
  • Use of 64-bit libraries on Windows instead of the out-of-the-box 32-bit libraries (bin/tomcat7.exe, bin/tcnative-1.dll)

Do not simply copy the configuration files from your existing Stash installation to your new installation. 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.

If you are using MySQL

Icon

Stash does not ship with the MySQL database driver.

You 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.

4. Start Stash

To start Stash, change directory in a terminal or command prompt to the <Stash installation directory> and run:

  • Windows:

    bin\start-stash.bat

  • Linux and Mac:

    bin/start-stash.sh

Note that the database schema migration task that runs when Stash is started after an upgrade can take a while, especially if the upgrade 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).

5. Rollback

If necessary, rolling back an upgrade should 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>.

Upgrading to Stash 2.12

Please also see:

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

Upgrading to Stash 2.11

Please also see:

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

Known issues

T Key Summary Status
Authenticate to retrieve your issues
No issues found

Upgrading to Stash 2.10

Please also see:

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

Known issues

Upgrading to Stash 2.9

Please also see:

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 upgrade task runs that optimizes the pull request refs for all repositories managed by Stash. It's important that you do not interrupt this upgrade process. You can track the progress of this in the Stash logs. See  STASH-3469 - Pull request references in the Git repository are never removed after merge or decline Closed .

Backup Client Upgrade Required

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

Known issues

T Key Summary Status
Authenticate to retrieve your issues
No issues found

Upgrading to Stash 2.8

Please also see:

Known issues

Upgrading to Stash 2.7

Please also see:

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

Upgrading to Stash 2.6

Please also see:

Known issues

T Key Summary Status
Bug STASH-3687 Application navigator use wrong URL Open
Authenticate to retrieve your issues
1 issue

Upgrading to Stash 2.5

Please also see:

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. 

Upgrading to Stash 2.4

Please also see:

Known issues

Upgrading to Stash 2.3

Please also see the Upgrade steps section above.

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

Known issues

Upgrading to Stash 2.2

Please see the Upgrade steps section above.

Known issues

Upgrading to Stash 2.1

Please also see the Upgrade 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 upgrade 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 upgrade 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.

Upgrading to Stash 2.0

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

Tomcat

For Stash 2.0, Tomcat has been upgraded from version 6 to 7. As part of that upgrade, 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 upgraded 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 Upgrade 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 at Step 4 of Installing Stash on Windows.

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 upgrade 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

Upgrading to Stash 1.3

This section provides specific notes for upgrading to Stash 1.3. See also the Upgrade steps section above.

Email server

An email server must be configured in Stash so that email notifications for pull request events can be sent. Please see Setting up your mail server for details.

Upgrading from Stash 1.3 beta

Click to see information about upgrading from the beta...

Stash 1.3 uses improved commenting compared to the 1.3 beta. This means that when you upgrade from the beta to Stash 1.3:

  • Pull request comments made in the beta against the diff will only appear in the activity, and not in the diff, in Stash 1.3. Future comments made on the same pull request in Stash 1.3 will behave as expected.
  • Reviewers, participants and watchers were added after the beta was released. After you upgrade, existing pull requests will not have participants or watchers. You can add reviewers by editing the pull requests and any future commenters will be added as a participant and watcher to the pull request as you would expect.

Known issues

Upgrading to Stash 1.2

Please see the  Upgrade steps  section above.

Known issues

Upgrading to Stash 1.1

Please see the  Upgrade steps  section above.

Upgrading from Stash 1.0.x to 1.1 or higher

Please also see the  Upgrade steps  section above.

SSH

When you restart Stash after upgrading to 1.1, Stash will automatically enable SSH access to your repositories, on the default port of 7999.

If you want to change the port, or are hosted behind a proxy or firewall, you may also need to change the SSH base URL so the clone URL's in Stash are correct. See the SSH admin instructions.

Developing for Stash

If you are a Stash plugin developer, please refer to our Stash developer documentation.

Checking for known issues and troubleshooting the Stash upgrade

If something is not working correctly after you have completed the steps above to upgrade your Stash installation, please check for known Stash issues and try troubleshooting your upgrade 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 upgrade and cannot solve it, please create a support ticket and one of our support engineers will help you.