Use Bitbucket in the enterprise

Still need help?

The Atlassian Community is here for you.

Ask the community

This page describes best practices for using Bitbucket Data Center and Server in enterprise environments. If you're evaluating Bitbucket, we suggest that you begin with Install a Bitbucket trial, instead of this page.

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

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




Atlassian offers two deployment options for Bitbucket.


Bitbucket Server

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

Bitbucket Data Center

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





If you manage your own Bitbucket site (it's not hosted by Atlassian), you'll have either a Bitbucket Server or Bitbucket Data Center license. 

Your Bitbucket license determines which features and infrastructure choices are available. 

We want all teams to get the most out of Bitbucket, so all the core features are available for everyone - including projects, repositories, pull requests and workflows. 

Feature comparison

Here's a summary of what you get with each license. 

Code and collaborationServer licenseData Center license

Pull requests

Review and discuss your code with your team before merging changes. Learn more about collaboration via pull requests

Draft multiple comments on files and code during a review process. Learn more about the new code review workflow

(tick)

(tick)

Branch permissions

Control what users can do on a single branch, branch type, or branch pattern within a repository or project. Learn more about branch permissions

(tick)

(tick)

Flexible workflows

Use centralized, forking, gitflow or forking workflows. Learn more about flexible workflows

(tick)

(tick)

Reviewer groups
Reviewer groups help quickly add the right reviewers in bulk for code reviews. Learn more about reviewer groups
(error)
(tick)
7.13+
Default tasks
Create consistent requirements when pull requests are opened with default tasks. Learn more about default tasks
(error)
(tick)
8.4+

Jira Software Server and Data Center integration

Connect Jira Server and Data Center and Bitbucket to automatically link issues and track progress simultaneously across both platforms. Learn more about integrating with Jira Software

(tick)

(tick)

Jira Software Cloud integration

Connect Jira Cloud and Bitbucket to automatically link issues and track progress simultaneously across both platforms. Learn more about integrating with Jira Software

(tick)
7.17+
(tick)
7.14+

CI/CD integrations

Seamlessly integrate Bitbucket with the world’s leading CI/CD vendors to streamline the path to production. Learn more about our CI/CD integrations

(tick)
(tick)
7.4+

Code insights

Get reports, annotations, and metrics to help you and your team improve code quality in pull requests throughout the code review process. Learn more about code insights

(tick)(tick)

APIs and 3rd party integrations

Use the Bitbucket API and 3rd party integrations to automate simple tasks, embed data into your own site, and customize your workflow. Learn more about APIs and 3rd party integrations

(tick)

(tick)

High availability and performance at scale

Clustering

Run Bitbucket on multiple nodes for high availability. Learn more about clustering

(error)

(tick)

Smart mirroring

Improve Git clone speeds for distributed teams working with large repositories. Learn more about Smart Mirroring

(error)

(tick)

Distributed Git storage

Increase performance and high availability of repositories. Learn more about Bitbucket Mesh

(error)
(tick)
8.0 +

Git LFS (Large File Storage)

Store large files without the need for an external object store. Learn more about Git LFS

(tick)(tick)

Disaster recovery

Keep your teams online and source code data available in the event that your primary system becomes unavailable. Learn more about disaster recovery

(error)

(tick)
6.8+

Search server

Connect Bitbucket to a remote search server for improved scalability (required for Data Center sites). Learn more about using a remote search server

(tick)

(tick)

Content Delivery Network (CDN) support

Improve geo-performance for distributed teams. Learn more about CDN

(error)
(tick)
6.8+
Security and compliance

(Enforced) merge checks

Stop pull requests from being merged until they meet the requirements that you’ve set. Learn more about merge checks

(tick)

(tick)

Advanced auditing

Get more insight into what is happening in your Bitbucket instance. Advanced auditing gives you the ability to track and log actions in your instance developing a security-relevant chronological record that can be exported and stored in third-party monitoring tools. Learn more about advanced auditing

(error)

(tick)
7.0+

HTTP access tokens

Create access tokens that aren't fixed to individual user accounts, for teams working on specific projects and repositories. Learn more about HTTP access tokens

(error)
(tick)
7.18+

OAuth 2.0

Configure Bitbucket as an OAuth 2.0 provider, allowing external applications to access Bitbucket. Learn more about incoming links

(error)
(tick)
7.20 +

Secret scanning

Get notified of secrets added in new commits and revoke secrets to prevent exposure. Learn more about secret scanning

(error)
(tick)
8.3 +
User management

External user directories

Store users in Active Directory, Crowd, Jira or another LDAP directory. Learn more about external user directories

(tick)

(tick)

Multiple identity providers
Use more than one IdP, and disable login methods you don't want to use (such as basic authentication). Learn more about using multiple IdPs
(error)
(tick)
7.12+

Single sign-on

Use a SAML or OpenID Connect identity provider for authentication and single sign-on. Learn more about SSO

(error)
(tick)
7.12+

Just-in-time provisioning

Just-in-time user provisioning (JIT provisioning) allows users to be created and updated automatically when they log in through SAML SSO or OpenID Connect (OIDC) SSO to Atlassian Data Center applications such as Jira, Confluence, or Bitbucket. Learn more about just-in-time provisioning

(error)

(tick)
7.5+
Infrastructure and Control

Rate limiting

Control how many external REST API requests users and automations can make. Learn more about rate limiting

(error)
(tick)
6.6+

Advanced repository management

Manage all of your repositories from global repositories page. Find repositories that are active, and identify which inactive ones are taking up space. Learn more about Advanced repository management

(error)
(tick)
7.13+

Repository archiving

Archive unused repositories to declutter your Bitbucket instance. Learn more about archiving and unarchiving repositories

(error)
(tick)
8.0+

Rolling upgrades

Upgrade to the latest bug fix update of the same feature release with no downtime. Learn more about rolling upgrades

(error)
(tick)
7.9+

Integrity tests for zero-downtime backup

Find and resolve any inconsistencies between the database and home directory, for example after restoring a backup. Learn more about Integrity tests for zero-downtime backup

(error)(tick)

App diagnostics

Get an overview of the health of your site, including potential performance issues relating to third-party apps. Learn more about app diagnostics

(tick)

(tick)

Business intelligence and monitoring

Data pipeline
Export all Confluence data for analysis in your preferred business intelligence platform. Learn more about the data pipeline
(error)
(tick)
7.13+
Deployment options

Your own hardware

Run Bitbucket on your own physical servers, virtualized servers, or in the data center of your choice.

(tick)

(tick)

Kubernetes

Run Bitbucket in Kubernetes cluster on Amazon EKS, Azure Kubernetes Service, Google Kubernetes Engine or on-premises. Learn more about Kubernetes support

(error)(tick)

AWS Quick Start and Cloud Formation Templates

Use our Cloud Formation Templates to deploy Bitbucket on AWS. Learn more about AWS Quick Start and Cloud Formation Templates

(error)

(tick)

Azure Quick Start Templates

Use our template to deploy Bitbucket on Azure. Learn more about Azure Quick Start Templates

(error)

(tick)




Platform requirements

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

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

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

Performance considerations

In general, Bitbucket 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 Bitbucket 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, Bitbucket is designed to queue incoming requests so as to avoid overwhelming the server.

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

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

High availability

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

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

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

Scalability

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

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

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

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

Bitbucket Data Center – see Adding and removing Data Center nodes for information about how you can rapidly provision extra capacity without downtime.

Provisioning

Some possible approaches to provisioning Bitbucket include:

Setting up a production environment

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

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

Administering a production environment

Upgrading Bitbucket
  • For production environments we recommend that you test the Bitbucket upgrade on a QA server before deploying to production. See the Bitbucket Server 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 Bitbucket.
Logging
  • Bitbucket instance logs can be found in  <Bitbucket home directory>/log. Logs for the bundled Tomcat webserver can be found in  <Bitbucket Server installation directory>/log. See Enable debug logging.
  • Bitbucket displays recent audit events for each repository and project (only visible to Bitbucket admins and system admins), and also creates full audit log files that can be found in the <Bitbucket home directory >/audit/logs directory. Note that Bitbucket 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 View and configure the audit log.]
Last modified on Nov 8, 2022

Was this helpful?

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