Stash is now known as Bitbucket Server.
See the

Unknown macro: {spacejump}

of this page, or visit the Bitbucket Server documentation home page.

Skip to end of metadata
Go to start of metadata

This page...

... describes best practice for using Stash in enterprise environments.

If you're evaluating Stash...

... we suggest that you begin with Getting started, instead of this page.

See also...

... Bitbucket Enterprise Resources for a comparison of Stash and Stash Data Center, our clustered Stash solution. 

Atlassian Stash is the Git code management solution for enterprise teams. It allows everyone in your organisation to easily collaborate on your Git repositories, while providing enterprise-grade support for:

  • user authentication
  • repository security
  • integration with your existing databases and development environment.

Atlassian offers two deployment options for Stash, to provide enterprise scaling and infrastructure flexibility, and to give administrators control over how Stash fits into their environment:

Stash Server

For most organizations, a single instance of Stash Server provides good performance. Continue reading this page for guidance on best practices in setting up a Stash server in a production environment.

Stash Data Center

For larger enterprises that require HA and greater performance at scale, Bitbucket Data Center resources uses a cluster of Stash nodes to provide Active/Active failover, and is the deployment option of choice. 

Your single instance of Stash Server can be easily upgraded to Stash Data Center when the time comes.


On this page:

Platform requirements for hosting Stash

Although Stash can be run on Windows, Linux and Mac systems, for enterprise use we only recommend, and support, Linux. This recommendation is based on our own testing and experience with using Stash.

See the Supported platforms page for details of the supported versions of Java, external databases, web browsers and Git.

See Installing Stash Data Center for detailed information about Stash Data Center requirements.

Performance considerations with Stash

In general, Stash is very stable and has low memory consumption. There are no scalability limits other than for Git hosting operations (clone in particular). We know this is the scalability limit of the product; the limit is proportional to the number of cores on the system.

As an example, data collected from an internal Stash instance indicate that for a team of approximately 50 developers, with associated continuous integration infrastructure, we see a peak concurrency of 30 simultaneous clone operations and a mean of 2 simultaneous clone operations. We conservatively expect that a customer with similar usage patterns would be capable of supporting 1000 users on a machine with 40 cores and a supporting amount of RAM. While we expect a peak concurrency larger than 40, Stash is designed to queue incoming requests so as to avoid overwhelming the server.

Stash Server – see Stash production server data for data from the Stash production instance we run internally at Atlassian.

Stash Data Center – see Bitbucket Data Center Performance for the results of our performance testing for clusters of different sizes.

High availability with Stash

If Stash is a critical part of your development workflow, maximizing Stash availability becomes an important consideration.

Stash Server – see High availability for Stash for the background information you need to set up Stash Server in a highly available configuration. 

Stash Data Center – see Failover for Bitbucket Data Center for information about how Stash Data Center provides HA and almost instant failover.


Stash is built with enterprise scaling and infrastructure flexibility in mind, giving administrators control over how Stash fits into their environment: 

  • For most organizations, a single instance of Stash Server provides good performance. Continue reading this page for guidance on best practice in setting up a Stash server in a production environment.
  • For larger enterprises that require HA and greater performance at scale, Stash Data Center uses a cluster of Stash nodes and is the deployment option of choice.

Your single instance of Stash Server can be easily upgraded to Stash Data Center when the time comes.

Stash Server – see Scaling Stash for information about how you can tune your Stash server to grow with your organisation's needs. See also Scaling Stash for Continuous Integration performance for information specific to Stash performance when CI tools poll Stash for changes.

Stash Data Center – see Adding cluster nodes to Stash Data Center for information about how you can rapidly provision extra capacity without downtime.

Provisioning Stash

Some possible approaches to provisioning Stash include:

Setting up Stash Server in a production environment

When setting up Stash for a production or enterprise environment, we highly recommend that you configure the following aspects:

Run Stash as a dedicated user
Install Stash as a service
Use an external database
  • For production environments Stash should use an external database, rather than the embedded database. Set up your external DBMS (for example MySQL) before starting Stash for the first time. This allows you to connect Stash to that DBMS using the Setup Wizard that launches when you first run Stash. See Connecting Stash to an external database.
Connect to your existing user directory
Secure the Stash home directory
  • For production environments the Stash home directory should be secured against unauthorised access. See Stash home directory.
Secure Stash with HTTPS
  • Access to Stash should be secured using HTTP over SSL, especially if your data is sensitive and Stash is exposed to the internet. See Securing Stash with HTTPS.
Enable SSH access to Git repositories
  • Enable SSH access for your Stash users to Git repositories in Stash so that they can add their own SSH keys to Stash, and then use those SSH keys to secure Git operations between their computer and the Stash server. See Enabling SSH access to Git repositories in Stash.
Change the context path for Stash
  • If you are running Stash behind a proxy, or you have another Atlassian application (or any Java web application), available at the same hostname and context path as Stash, then you should set a unique context path for Stash. See Moving Stash to a different context path.

Administering Stash in a production environment

Upgrading Stash
  • For production environments we recommend that you test the Stash upgrade on a QA server before deploying to production. See the Stash upgrade guide.
Backups and recovery
  • We highly recommend that you establish a data recovery plan that is aligned with your company's policies. See Data recovery and backups for information about tools and backup strategies for Stash.
  • Stash server logs can be found in <STASH_HOME>/log. Logs for the bundled Tomcat webserver can be found in <Stash installation directory>/log. See Stash debug logging.
  • Stash displays recent audit events for each repository and project (only visible to Stash admins and system admins), and also creates full audit log files that can be found in the <Stash home directory >/audit/logs directory. Note that Stash has an upper limit to the number of log files it maintains, and deletes the oldest file when a new file is created – we recommend an automated backup of log files. See Audit logging in Stash.
  • No labels