Upgrade Bitbucket from an archive file

Still need help?

The Atlassian Community is here for you.

Ask the community

This page describes how to upgrade Bitbucket Data Center using a zip or tar.gz file.

Upgrading to any later version is free if you have current software maintenance. See our Licensing FAQ to find out more.


Other ways to upgrade Bitbucket:

On this page:



Before you begin

Before you upgrade Bitbucket you should answer these questions about your instance.

Is manual the right upgrade method for you?
Tell me more...

You can choose to upgrade using the installer, or, if the installer is not suitable for your situation you can use an archive file to update your Bitbucket instance. Only use an archive file to update Bitbucket if the installer is not suitable for your situation, as the installer is the the recommended approach to upgrade for most use cases.

Read about how to upgrade using the installer.

Are you eligible to upgrade?
Tell me more...

To check if software maintenance is current for your license, go to > Licensing and make sure the license support period has not expired.

If your support period has expired, follow the prompts to renew your license and reapply it before upgrading.

Have our support platforms changed?
Tell me more...

Check the Supported platforms page for the version of Bitbucket you are upgrading to. This will give you info on supported operating systems, databases and browsers.

Have you modified your server.xml file?
Tell me more...

In Bitbucket 5 we changed where you configure properties such as port numbers, context paths, and access protocol (among other things) to centralize custom configuration to a single directory and file, and to make upgrading easier for future releases.

Upgrading from any version earlier than or including Bitbucket Server 4.14 to Bitbucket Server 5.0 or later requires that you manually migrate any changes to the server.xml file to the bitbucket.properties file.

See the page Migrate customizations from server.xml to bitbucket.properties for instructions on locating your server.xml file and how to migrate your customizations.

Plan your upgrade

1. Determine your upgrade path

Check the Supported platforms page to determine if your environment meets the minimum requirements to run the latest version of Bitbucket. Also, check the End of support announcements

You can update from any previous version of Bitbucket Data Center to the latest version, as there is no required upgrade path. If you’re upgrading from Bitbucket Server to the Data Center-only version, check the guide on how to do this: Upgrade from Bitbucket Server to Bitbucket Data Center.

Bitbucket 8.x is a major upgrade

Be sure to read the Bitbucket 8.0 release notes, take a full backup, and test your upgrade in a non-production environment before upgrading your production site.

Upgrading from a version older than Bitbucket 8.x disables all user-installed apps on startup

Be sure to update your own apps and check the Atlassian Marketplace to ensure third-party apps are compatible with Bitbucket Data Center and Server 8.x before upgrading.

tip/resting Created with Sketch.

Upgrading to the next bug fix update

If you are upgrading a multi-node Bitbucket cluster to the next bug fix update (for example, from 8.0.0 to 8.0.1), you can upgrade with no downtime.

2. Complete pre-upgrade checks

  1. Check the Version specific upgrade notes for the version you plan to upgrade to (and any in between).
  2. Go to Administration and select Support Tools. Then, review the Log analyzer for any issues that may need to be resolved.
  3. Check the compatibility of your apps with the version you plan to upgrade to.

    1. Go to Administration and select Manage apps. Then, select Bitbucket update check.
    2. Choose the version you plan to upgrade to. Then, select Check.

      If you have incompatible apps

      If your users rely on particular apps, you may want to wait until they are compatible before upgrading Bitbucket. App vendors generally update their apps very soon after a major release.

      Good to know:

      • If you're performing a major version upgrade, user-installed apps will be disabled. You will need to enable your apps after successfully upgrading, regardless of compatibility with Bitbucket.

      • You can disable an app temporarily if it is not yet compatible. 

3. Upgrade Bitbucket in a test environment

  1. Create a staging copy of your current production environment.
  2. Follow the steps below to upgrade your test environment.
  3. Test any unsupported apps, customizations and proxy configuration (if possible) before upgrading your production environment.
   

Upgrade Bitbucket

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

If necessary, rolling back an upgrade can only be performed by restoring a backup of both the Bitbucket home directory and the Bitbucket database – rolling back requires a consistent home directory and database. You can then reinstall the previous version of the application to the installation directory. Read the Rollback section for more details.

 

4. Back up your data

  1. Determine which backup strategy to use. 

    Summary of the different backup strategies for Bitbucket...

    For Bitbucket Data Center (version 4.8 or later) instances, you can use Zero Downtime BackupDIY Backup, or take snapshots of the shared home directory (on NFS) and database while all nodes are stopped. 

    For Bitbucket mirrors, the home directory doesn't store any persistent state that can't be reconstructed from the primary Bitbucket instance, but you should still make sure you have a backup of at least the important configuration files such as SSL certificate, server.xml,  config/ssh-server-keys.pem,  bitbucket.properties file, and so on in a safe place. See  How do I back up my mirrors? for more information.

    See the article Data recovery and backups for detailed information and guidance on creating an effective backup strategy.

  2. Back up all the data in your Bitbucket home directory and external database.


5. Stop the application

For Linux...

Stop Bitbucket Data Center from a terminal by changing to the <Bitbucket installation directory> and running:

bin/stop-bitbucket.sh
For Bitbucket Data Center...

Be sure to stop all nodes of Bitbucket Data Center, perform the steps to upgrade for a single node first, then repeat the process on each cluster node.

See the page Start and stop Bitbucket for more detailed instructions.

6. Download Bitbucket

Download the appropriate file for your operating system - https://www.atlassian.com/software/bitbucket/download-archives.

7. Extract the file and upgrade Bitbucket

  1. Extract (unzip) the files to a directory (this is your new installation directory, and must be different to your existing installation directory).

    Which user account should I do this with?

    Use the same user account to extract and to run Bitbucket to avoid permission issues at startup. For production installations, we recommend you use new dedicated user that will run Bitbucket on your system.

    See the page Running Bitbucket Data Center with a dedicated user for more details.

  2. Update the value of BITBUCKET_HOME in the <Bitbucket installation directory> /bin/set-bitbucket-home.sh file so the new Bitbucket installation points to your existing Bitbucket home directory  (if you use a BITBUCKET_HOME environment variable to specify the home directory location, no change is required).

8. Start Bitbucket

For Bitbucket Data Center, Bitbucket Server and the remote Elasticsearch instance must be started separately. It is a requirement of the Bitbucket Data Center setup that you have only one remote Elasticsearch instance for your entire cluster, as described in Installing Bitbucket Data Center. The start-bitbucket.sh command starts both Bitbucket and Elasticsearch and should not be used to start your Bitbucket Data Center application nodes.

When using a remote Elasticsearch instance, instead of the bundled Elasticsearch instance, start Bitbucket Server by running start-webapp.sh instead of start-bitbucket.sh.

To start Bitbucket Data Center

  1. Start each of your application nodes. From <Bitbucket installation directory>, run this command for each node:

    For Windows

    bin\start-webapp.bat

    For Linux

    bin/start-webapp.sh
  2. Start your Elasticsearch node. From <Bitbucket installation directory>, run this command:

    For Windows

    bin\start-search.bat


    For Linux

    bin/start-search.sh

Read the page Start and stop Bitbucket for more details.





Rollback

If necessary, rolling back an update can only be performed by restoring a backup of both the Bitbucket Server home directory and the Bitbucket Server database – rolling back requires a consistent home directory and database. You can then reinstall the previous version of the application to the installation directory. Never start an older binary against an upgraded home directory.

 

Version-specific update notes


This section provides specific update notes for each version of Bitbucket Data Center. These notes supplement the primary upgrade instructions above. You should read the relevant sections for each version between your current version of the application and the version you are upgrading to.

Bitbucket 8 release notes...

Bitbucket Data Center 8.19 update notes (Long Term Support)

You should also see:

Bitbucket Data Center 8.18 update notes

You should also see:

Bitbucket Data Center 8.17 update notes

You should also see:

Bitbucket Data Center 8.16 update notes

You should also see:

Bitbucket Data Center 8.15 update notes

You should also see:

Bitbucket Data Center and Server 8.14 update notes

You should also see:


Bitbucket Data Center and Server 8.13 update notes

You should also see:


Bitbucket Data Center and Server 8.12 update notes

You should also see:


Bitbucket Data Center and Server 8.11 update notes

You should also see:

Bitbucket Data Center and Server 8.10 update notes

You should also see:

Bitbucket Data Center and Server 8.9 update notes (Long Term Support)

You should also see:

Bitbucket Data Center and Server 8.8 update notes

You should also see:

Bitbucket Data Center and Server 8.7 update notes

You should also see:

Bitbucket Data Center and Server 8.6 update notes

You should also see:

Bitbucket Data Center and Server 8.5 update notes

You should also see:

Bitbucket Data Center and Server 8.4 update notes

You should also see:

Bitbucket Data Center and Server 8.3 update notes

You should also see:

Bitbucket Data Center and Server 8.2 update notes

You should also see:

Bitbucket Data Center and Server 8.1 update notes

You should also see:

Bitbucket Data Center and Server 8.0 update notes

You should also see:

Bitbucket 7 release notes...

Bitbucket Data Center and Server 7.21 update notes (Long Term Support)

You should also see:

Bitbucket Data Center and Server 7.20 update notes

You should also see:

Bitbucket Data Center and Server 7.19 update notes

You should also see:

Bitbucket Data Center and Server 7.18 update notes

You should also see:

Bitbucket Data Center and Server 7.17 update notes

You should also see:

Bitbucket Data Center and Server 7.16 update notes

You should also see:

Bitbucket Data Center and Server 7.15 update notes

You should also see:

Bitbucket Data Center and Server 7.14 update notes

You should also see:

Bitbucket Data Center and Server 7.13 update notes

You should also see:

Bitbucket Data Center and Server 7.12 update notes

You should also see:

Bitbucket Data Center and Server 7.11 update notes

You should also see:

Bitbucket Data Center and Server 7.10 update notes

You should also see:

Bitbucket Server 7.9 update notes

You should also see:

Bitbucket Server 7.8 update notes

You should also see:

Bitbucket Server 7.7 update notes

You should also see:

Bitbucket Server 7.6 update notes

You should also see:

Bitbucket Server 7.5 update notes

You should also see:

Bitbucket Server 7.4 update notes

You should also see:

New Data Center apps check as part of your license upgrade

Upgrading to a Bitbucket Data Center license now comes with a new apps check. Before we apply your new Bitbucket license, we’ll show you if any of your installed apps will need to be upgraded to the Data Center approved version.

We’ve also introduced new status messages in the Manage apps section of your admin console, so you can clearly see if any apps will require a new license.

New statusHost product licenseWhat it means

DATA CENTER LICENSE AVAILABLE

Evaluation license

The app vendor offers a Data Center version of this app. If you switch to a paid Data Center product license, you’ll need to upgrade this app license to Data Center.

LICENSE INCOMPATIBLE

Full license

The app vendor offers a Data Center version of this app. Your Server app license is no longer compatible with the product. This means the app has either stopped working, or functionality has been lost or compromised. You need to add a Data Center license.

Learn more about upgrading your Server apps after you move to Data Center

Build status data migration

When upgrading to Bitbucket Server 7.4, you may notice an increased load on your database and application server. This is normal. It’s due to an asynchronous upgrade task that needs to run to migrate your application’s build status data.

While the upgrade task is running, your application will be available and able to serve requests, so your team can continue working as usual.

The upgrade task will run automatically around two minutes after your application starts up. In a multi-node cluster, it will run on a node picked by the system. How long it takes will depend on the size of the data that needs to be migrated. For example, for small instances it can take 10 minutes, and for large instances it can take over an hour.

Before upgrading to Bitbucket Server 7.4, you should test HTTP hosting in a staging environment that mirrors your production setup. This especially includes any installed apps, as app-provided servlet filters may be broken by async HTTP.


Bitbucket Server 7.3 update notes

You should also see:


Bitbucket Server 7.2 update notes

You should also see:

Bitbucket Server 7.1 update notes

You should also see:

Bitbucket Server 7.0 update notes

You should also see:

If you are considering upgrading to bitbucket 7.0 or higher and are using version 2.8 or earlier of the Bitbucket branch source Jenkins plugin, there is a known issue that can cause builds to fail. This is because merges are performed lazily in order to manage scaling while changes to pull requests happen continuously.
See BSERV-12284 - Getting issue details... STATUS .

Bitbucket 6 release notes...

Bitbucket Server 6.10 update notes

You should also see:

Bitbucket Server 6.9 update notes

You should also see:

Bitbucket Server 6.8 update notes

You should also see:

Bitbucket Server 6.7 update notes

You should also see:

Bitbucket Server 6.6 update notes

You should also see:

Bitbucket Server 6.5 update notes

You should also see:

Bitbucket Server 6.4 update notes

You should also see:

Bitbucket Server 6.3 update notes

You should also see:

Bitbucket Server 6.2 update notes

You should also see:

Bitbucket Server 6.1 update notes

You should also see:

Bitbucket Server 6.0 update notes

You should also see:


To upgrade to Bitbucket Server 5+, you must migrate customizations to bitbucket.properties

Be sure to carefully read the Bitbucket Server upgrade guide to determine what impact this change may have on your instance. The page Migrate server.xml customizations to bitbucket.properties has specifics on which properties need to be migrated, how to migrate them, and includes some examples that demonstrate how to migrate some common customizations.

Start script changes

Starting from Bitbucket Server 5.0, some startup scripts had their name prefixed with an underscore. These scripts have been deprecated, and you should no longer call these scripts directly. This is to avoid confusion, because previously there were multiple start and stop scripts, making it easy to confuse which one to call. Now, there is only one script, that begins with "start" and one that begins with "stop".


Known issues

P Key Summary Status
Loading...
Refresh

Bitbucket 5 release notes...

Bitbucket Server 5.16 update notes

You should also see:


Bitbucket Server 5.15 update notes

You should also see:

Bitbucket Server 5.14 update notes

You should also see:


Bitbucket Server 5.13 update notes

You should also see:

Bitbucket Server 5.12 update notes

You should also see:

Bitbucket Server 5.11 update notes

You should also see:

Bitbucket Server 5.10 update notes

You should also see:

Bitbucket Server 5.9 update notes

You should also see:

Bitbucket Server 5.8 update notes

You should also see:

Bitbucket Server 5.7 update notes

You should also see:

Bitbucket Server 5.6 update notes

You should also see:

Bitbucket Server 5.5 update notes

You should also see:

Bitbucket Server 5.4 update notes

You should also see:

Bitbucket Server 5.3 update notes

You should also see:

Bitbucket Server 5.2 update notes

You should also see:

Bitbucket Server 5.1 update notes

You should also see:

Bitbucket Server 5.0 update notes

You should also see:


To upgrade to Bitbucket Server 5+, you must migrate customizations to bitbucket.properties

Be sure to carefully read the Bitbucket Server upgrade guide to determine what impact this change may have on your instance. The page Migrate server.xml customizations to bitbucket.properties has specifics on which properties need to be migrated, how to migrate them, and includes some examples that demonstrate how to migrate some common customizations.

Start script changes

In Bitbucket Server 5.0, some startup scripts have had their name prefixed with an underscore. These scripts have been deprecated, and you should no longer call these scripts directly. This is to avoid confusion, because previously there were multiple start and stop scripts, making it easy to confuse which one to call. Now, there is only one script, that begins with "start" and one that begins with "stop".

BitbucketServer does not support reverse proxies using AJP connections

Starting from version 5.0, Bitbucket Server does not support reverse proxies using AJP connections. While never officially supported, previous versions of Bitbucket Server could use AJP connections. However, with changes to how Bitbucket Server uses Tomcat, using AJP connections with Bitbucket Server (or Data Center) 5.0+ will cause the application to fail on startup.

Known issues

P Key Summary Status
Loading...
Refresh


Bitbucket 4 release notes...

Bitbucket Server 4.14 update notes

You should also see:

Known issues

P Key Summary Status
Loading...
Refresh

Bitbucket Server 4.13 update notes

You should also see:

Known issues

P Key Summary Status
Loading...
Refresh

Bitbucket Server 4.12 update notes

You should also see:


Do NOT upgrade to Git 2.11+

Any version after Git 2.11.0 (including future 2.12+ releases) cannot be used with Bitbucket Server. Bitbucket Server 4.12 will fail on startup if Git 2.11+ is detected. Only upgrade to versions of Git which are explicitly marked supported on our Supported Platforms page.

BSERV-9388 - Getting issue details... STATUS


Known issues

P Key Summary Status
Loading...
Refresh

Bitbucket Server 4.11 update notes

You should also see:

Known issues

P Key Summary Status
Loading...
Refresh

Bitbucket Server 4.10 update notes

You should also see:

Known issues

P Key Summary Status
Loading...
Refresh

Bitbucket Server 4.9 update notes

You should also see:

Known issues

P Key Summary Status
Loading...
Refresh

Bitbucket Server 4.8 update notes

You should also see:

Known issues

P Key Summary Status
Loading...
Refresh

Bitbucket Server 4.7 update notes

You should also see:

Known issues

P Key Summary Status
Loading...
Refresh

Bitbucket Server 4.6 update notes

Also see:

Known issues

P Key Summary Status
Loading...
Refresh

Bitbucket Server 4.5 update notes

Also see:

Known issues

P Key Summary Status
Loading...
Refresh

Bitbucket Server 4.4 update notes

Also see:

Known issues

P Key Summary Status
Loading...
Refresh

Bitbucket Server 4.3 update notes

Also see:

Known issues

P Key Summary Status
Loading...
Refresh

Bitbucket Server 4.2 update notes

Also see:

Known issues

P Key Summary Status
Loading...
Refresh

Bitbucket Server 4.1 update notes

Also see:

Known issues

P Key Summary Status
Loading...
Refresh

Bitbucket Server 4.0 update notes

Also see:

Do you rely on user-installed add-ons?

Your plugins may not be compatible with Bitbucket Server 4.0 (yet)

Upgrading from Stash to Bitbucket Server will disable all user-installed add-ons, whether they are 3rd-party add-ons from Atlassian Marketplace, or your own custom add-ons. User-installed add-ons will need to be checked, upgraded and enabled again once you've finished the upgrade process. You should check the marketplace listing for 3rd-party add-ons to determine if there is a release that is compatible with Bitbucket Server 4.0. Unless they have been updated to work with Bitbucket Server 4.0, existing add-ons (or plugins) that use the API interfaces that have been removed in Bitbucket Server 4.0 will not work. Similarly, custom add-ons need to be upgraded for Bitbucket Server compatibility. See the documentation on how to update your add-on for details.

If you are upgrading from Stash 3.x to Bitbucket Server 4.x, you should be aware that most user-installed add-ons will be incompatible with Bitbucket Server 4.0. After upgrading, 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 will remain disabled. 

New dedicated user account 'atlbitbucket'

A new dedicated user account will be created to run Bitbucket Server, called atlbitbucket. During the upgrade process, you will have an option to delete the dedicated user account for running Stash, named atlstash. For most users, deleting this dedicated user account won't have any negative consequences, however if you rely on this dedicated user accounts, for example in custom backup scripts, you will need to update the user account in those scripts.

Updates to logger names

If you have customized your logging configuration by manually editing the logback.xml file (using steps found in the Configure Stash Logging KB article), you should be aware of changes to several logger names that may require you to update some of your configuration files.

See the logger name changes...
Stash logger nameBitbucket Server logger name 
stash.application
bitbucket.application
stash.profiler bitbucket.profiler
stash.access-logbitbucket.access-log
stash.audit-logbitbucket.audit-log
stash.mail-logbitbucket.mail-log

Important security improvement which may require configuration changes

Previous to Bitbucket Server 4.0, a security constraint for redirecting from HTTP to HTTPS was not enforced, meaning users could type "http://<bitbucketserver-url>" into their browser and still be shown a functioning version of Bitbucket Server (or Stash). Included with the release of Bitbucket Server 4.0 was a fix to enforce that security constraint. Using the previous security configuration with Bitbucket Server 4.0 means trying to access the application over an insecure connection, when users type "http" when trying to get to the application, they could encounter erroneous behavior. 

As part of upgrading from Stash to Bitbucket Server, it is recommended you update your security configuration in order to avoid encountering this problem. See this Knowledge Base article for more information and specific instructions on addressing this: Redirect HTTP Requests to HTTPS.

Known issues

P Key Summary Status
Loading...
Refresh

Stash release notes
Stash 3 release notes...

Stash 3.11 update notes

Also see:

Known issues

P Key Summary Status
Loading...
Refresh

Stash 3.10 update notes

Also see:

Are you using Git 2.2x - 2.4.0?

Git 2.2.x - 2.4.0 have reported performance issues when interacting with NFS. Hence, these versions are currently not supported for Stash Data Center or for Stash Server installations that use NFS mounts for the home directory.

Known issues

P Key Summary Status
Loading...
Refresh

Stash 3.9 update notes

Also see:

Are you using JIRA as a Crowd server?

Stash 3.9 cannot use JIRA 6.4 as a Crowd server due to a bug in JIRA 6.4.  Please upgrade to JIRA 6.4.1 before upgrading Stash. (Note that Stash 3.7.2 and 3.8.0 contained a workaround for the bug but the workaround was removed in Stash 3.9)

Known issues

P Key Summary Status
Loading...
Refresh

Stash 3.8 update notes

Also see:

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 will not have to be redone for future upgrades.

(warning) You still need to update your custom configurations in shared/server.xml for the upgrade to Stash 3.8.

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

P Key Summary Status
Loading...
Refresh

Stash 3.7 update notes

Also see:

Do you use JIRA 6.4?

JIRA 6.4 has a known issue with Stash versions 3.4.3 to 3.7.1, which prevents the user synchronization from working. This will only affect you if you use JIRA to manage your users in Stash, and is fixed in Stash 3.7.2.

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

P Key Summary Status
Loading...
Refresh

Stash 3.6 update notes

Also see:

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

P Key Summary Status
Loading...
Refresh

Stash 3.5 update notes

Also see:

Stash home directory location

Stash 3.5 and later versions no longer allow the Set the 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

P Key Summary Status
Loading...
Refresh

Stash 3.4 update notes

Also see:

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

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

Known issues

P Key Summary Status
Loading...
Refresh

Stash 3.3 update notes

Also see:

Known issues

P Key Summary Status
Loading...
Refresh

Stash 3.2 update notes

Upgrading to Stash 3.2 or later from Stash 3.1 or earlier is irreversible – please see the Home directory migration section below.

Also see:

Note that:

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

Before Stash 3.2 it was possible to override the location of the following subfolders in the Stash home directory, using undocumented environment variables or system properties:

  • export
  • bin
  • caches
  • config 
  • data
  • lib
  • lib/native
  • log
  • plugins
  • tmp


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 Change data collection settings.

Known issues

P Key Summary Status
Loading...
Refresh

Stash 3.1 update notes

Also see:

Note that:

Known issues

P Key Summary Status
Loading...
Refresh

Stash 3.0 update notes

Stash no longer supports Java 6

Stash 3.0 requires at least Java 7, and supports Java 8.

Please see the End of support announcements.

Your plugins may not be compatible with Stash 3.0

The interfaces in the Stash API for plugin developers that were deprecated in Stash 2.11 and earlier have been removed in Stash 3.0. This means that, unless they have been updated to work with Stash 3.0, existing Stash add-ons (or plugins) that use these interfaces will not work with Stash 3.0.

Please see the section below about Stash add-on incompatibilities for more details.

Also see:

Note that:

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

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.

Add-onJAR file nameStash 3.0 compatible version
Custom Navigation Plugincustom-navigation-plugin2.0.3

Stash Archive Plugin

stash-archive1.3.0
Repository git operations pluginstash-git-ops-plugin1.2.1
Stash Auto Unapprove Pluginstash-auto-unapprove-plugin

1.1

Stash Protect Unmerged Branch Hookstash-protect-unmerged-branch-hook1.1
Stash Reviewer Suggesterstash-suggest-reviewers1.2
Stash Web Post Hooks Pluginstash-web-post-receive-hooks-plugin1.1.0
Realtime Editor for Stashstash-editor-plugin1.0.6
Known issues

P Key Summary Status
Loading...
Refresh

Stash 2 release notes...

Stash 2.12 update notes

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

P Key Summary Status
Loading...
Refresh

Stash 2.11 update notes

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

P Key Summary Status
Loading...
Refresh

Stash 2.10 update notes

Also see:

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

Known issues

P Key Summary Status
Loading...
Refresh

Stash 2.9 update notes

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

P Key Summary Status
Loading...
Refresh

Stash 2.8 update notes

Also see:

Known issues

P Key Summary Status
Loading...
Refresh

Stash 2.7 update notes

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

P Key Summary Status
Loading...
Refresh

Stash 2.6 update notes

Also see:

Known issues

P Key Summary Status
Loading...
Refresh

Stash 2.5 update notes

Also see:

Known issues

P Key Summary Status
Loading...
Refresh

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.

Stash 2.4 update notes

Also see:

Known issues

P Key Summary Status
Loading...
Refresh

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

P Key Summary Status
Loading...
Refresh

Stash 2.2 update notes

Please see the update steps section above.

Known issues

P Key Summary Status
Loading...
Refresh

Stash 2.1 update notes

Please also see the update steps section above.

Known issues

P Key Summary Status
Loading...
Refresh

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 customized server.xml (for example, for portpath or hostname), you can not simply copy your own version across to the updated Stash; you must reapply your customizations 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 refer to the  Running Bitbucket Server as a Windows service page for 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 directory>/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

P Key Summary Status
Loading...
Refresh



Last modified on Oct 23, 2023

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.