Stash Latest (2.8) : Stash upgrade guide

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

Upgrading to Stash 2.8

Please also see:

Known issues

Type Key Summary Status
Bug STASH-3884 Non-ASCII values used as branch model prefixes/branch names don't work in MSSQL Open
Bug STASH-3909 Creating a branch containing double quotes in the name will fail on Windows Open
Authenticate to retrieve your 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

Type Key Summary Status
Bug STASH-3871 Stash 2.7 fails to start with MySQL when binary logging is enabled Open
Bug STASH-3829 Stash treats "<char - >" as An invalid or illegal XML character in the comments Open
Bug STASH-3828 Stash fails to start in Turkish environment Open
Bug STASH-3891 Git's native .mailmap handling generates 500 errors in Stash for Git 1.8.2 to 1.8.4 Open
Bug STASH-3803 Specifying 'since' and 'until' parameters on commits list only works if there aren't enough commits to trigger infinite scroll Open
Bug STASH-3773 Number of required approvals doesn't get updated when approving Open
Authenticate to retrieve your issues

Upgrading to Stash 2.6

Please also see:

Known issues

Type Key Summary Status
Bug STASH-3687 Application navigator use wrong URL Open
Bug STASH-3633 Repository Quick Search does not match personal 'projects' by name Open
Authenticate to retrieve your issues

Upgrading to Stash 2.5

Please also see:

Known issues

Type Key Summary Status
Bug STASH-3702 Invalid markdown list rendering Open
Bug STASH-3635 Html in PR comments not encoded Open
Bug STASH-3624 SocketException on Solaris 10 Open
Bug STASH-3589 Vertical alignment of back link on user profile screen is off Open
Bug STASH-3557 Stash favicon looks bad on non white backgrounds Open
Bug STASH-3251 NPE in SshScmRequestCommandAdapter.java:238 Open
Authenticate to retrieve your 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

Type Key Summary Status
Bug STASH-3419 In full source display mode, longest line is cut off if horizontal scroll bar Open
Bug STASH-3163 Driver not available when running Stash as Windows service using $STASH_HOME/lib Open
Authenticate to retrieve your 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

Type Key Summary Status
Bug STASH-3461 Stash upgrade task does not check for database schema validity Open
Bug STASH-3308 Git command authentication failure causing the user to enter captcha before maxmimum attempts are met. Open
Bug STASH-3296 Using "Load newer activities" on pull requests drops some activities Open
Bug STASH-3288 UI broken after inactive user added to pull request Open
Bug STASH-3279 URL not linked correctly when surrounding by parenthesis Open
Authenticate to retrieve your issues

Upgrading to Stash 2.2

Please see the Upgrade steps section above.

Known issues

Type Key Summary Status
Bug STASH-3295 Comment Date format changes from relative to absolute dates unexpectedly Open
Bug STASH-3251 NPE in SshScmRequestCommandAdapter.java:238 Open
Bug STASH-3204 DataIntegrityViolationException when configuring Trusted Application Open
Authenticate to retrieve your issues

Upgrading to Stash 2.1

Please also see the Upgrade steps section above.

Known issues

Type Key Summary Status
Bug STASH-3319 atlas-install-plugin fails if the plugin is larger than 1 MB Open
Bug STASH-3163 Driver not available when running Stash as Windows service using $STASH_HOME/lib Open
Authenticate to retrieve your 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

Type Key Summary Status
Bug STASH-2862 Non-ASCII values used in branch permissions don't work in MSSQL Open
Bug STASH-2898 Tomcat fails to start up on 64-bit Windows with error tc-native-1.dll: Can't load IA 32-bit .dll Open
Bug STASH-2889 Markdown: colon ':' in image urls is not accepted by current implementation of markdown Open
Authenticate to retrieve your 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

Type Key Summary Status
Bug STASH-2818 The latest custom JIRA issue key regex is not used to reindex the old commits Open
Bug STASH-2744 Pull Request race condition between push and attributed activity author Open
Authenticate to retrieve your issues

Upgrading to Stash 1.2

Please see the  Upgrade steps  section above.

Known issues

Type Key Summary Status
Bug STASH-2746 Windows service behaves poorly (doesn't shut down, reports successful startup too early) Open
Bug STASH-2658 Web resource compression occurs before web resource copying on incremental plugin builds Open
Authenticate to retrieve your 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.