Administer code search
Bitbucket Server allows you to search through your code to find exactly what you’re looking for right from the search bar. You can restrict your search results to a specific project or repository using search filters. You can also search for code in a particular language (e.g., lang:java) or with a particular file extension (e.g., ext:css).
Head to Bitbucket search syntax for details on the search syntax.
This page explains how Bitbucket Server and Data Center uses Elasticsearch, how to configure Elasticsearch to fit the needs of your organization, and provides some tips for troubleshooting common problems.
About Elasticsearch
Code search is powered by Elasticsearch, which indexes the content of Bitbucket Server repositories in real time. Elasticsearch comes bundled with Bitbucket Server and is managed by Bitbucket Server automatically. Under most circumstances it should not need to be managed manually by an administrator.
Important details and requirements about Bitbucket and Elasticsearch
This section outlines important considerations for using Bitbucket and Elasticsearch. Read the section appropriate for your installation.
For all Bitbucket Server/Data Center installations
- Elasticsearch is required to run Bitbucket Server and Data Center (although code search can be disabled entirely if needed).
- From Bitbucket Server 5.7 onwards, only Elasticsearch 5.5 will be supported. Support for Elasticsearch 2.3 ended with Bitbucket Server 5.7 in 2018.
You can configure what is indexed for code search to exclude various types of forked repositories to save disk space.
Data Center will continue support for both Elasticsearch 2.3 and 5.5, only until the release of Bitbucket 6.0 to allow an upgrade to be planned. At this time, Elasticsearch 2.3 will no longer be supported for Data Center.
For Bitbucket Server installed using the installer
- If you install Bitbucket Server using the installer Elasticsearch is configured to work out of the box.
- Bitbucket Sever's bundled Elasticsearch instance requires ports 7992 and 7993 to be available. This is not configurable when using the bundles Elasticsearch instance. If these ports are not available, you will need to Install and configure a remote Elasticsearch server to work with Bitbucket.
For Bitbucket Server installed using an archive file (.zip/.tar.gz)
After unzipping the archive files, you need to copy the contents of the
<Bitbucket installation directory>/elasticsearch/config-templatedirectory to the<Bitbucket home>/shared/searchdirectory, or Bitbucket won't start correctly. Details can be found in the archive installation instructions for Windows and Linux.
For Bitbucket Data Center installations
- Bitbucket Data Center requires a remote Elasticsearch instance, as it is not bundled or installed for Bitbucket Data Center. You must install and configure a remote Elasticsearch instance, as described in the installation instructions for Bitbucket Data Center.
- Bitbucket Data Center can have only one remote connection to Elasticsearch for your cluster. This may be a standalone Elasticsearch installation or a clustered installation behind a load balancer.
- Code search is not critical for high availability, however it is possible run a cluster of Elasticsearch nodes to achieve high availability, although Atlassian cannot guarantee support for such a setup in event you encounter problems.
Change the username and password for accessing Elasticsearch
There are two ways you can change the user credentials Bitbucket uses to access Elasticsearch.
- Configure the details of your Elasticsearch instance within the Bitbucket Server UI, or
- Configure the details of your Elasticsearch instance within the
bitbucket.propertiesfile.
If an Elasticsearch parameter is set from within the bitbucket.properties file, it cannot be edited later from the admin UI. Any changes that need to be made to the Elasticsearch configuration must be made within the bitbucket.properties file.
Go to 
> Server settings > Search.
Here you can see the current configuration of Elasticsearch, including the port and user credentials for accessing Elasticsearch.
Use a remote Elasticsearch instance with Bitbucket Data Center
Bitbucket Data Center requires a remote Elasticsearch instance, as it is not bundled or installed for Bitbucket Data Center. This may be a standalone Elasticsearch installation or a clustered installation behind a load balancer.
For instructions on setting up a single remote instance of Elasticsearch to use with Bitbucket Data Center, see the Bitbucket Data Center installation instructions.
For guidance on using a clustered Elasticsearch installation with Bitbucket Data Center, see the page Install and configure a remote Elasticsearch server, but note that Atlassian cannot guarantee support for such a setup in event you encounter problems.
Start Bitbucket Data Center with a remote Elasticsearch instance
Because Bitbucket Data Center requires a remote Elasticsearch instance, you need to start Bitbucket Data Center with an argument that won't try to start the bundled Elasticsearch that comes with Bitbucket Server.
To start Bitbucket when using a remote Elasticsearch instance
| For Linux | start-bitbucket.sh --no-search |
|---|---|
| For Windows | start-bitbucket.bat /no-search
|
Troubleshooting and frequently asked questions about Elasticsearch
I can't configure Elasticsearch settings from the UI because the fields are grayed out
Your Elasticsearch configurations were set within the bitbucket.properties file. If a parameter is set in the bitbucket.properties file, it cannot be edited later from the admin UI. Any changes that need to be made to the Elasticsearch configuration must be made within the bitbucket.properties file.
My remote Elasticsearch instance is using up a lot of disk space
With Bitbucket 5.1+ you can configure the Elasticsearch search indexes to exclude certain types of forked repositories, which can save disk space when your company uses a fork-based workflow for development. See the page Bitbucket Server config properties - Search for the options available to change what is indexed for code search. Note that excluding content from being indexed can prevent such content from ever appearing in code search results, but will not prevent the repositories themselves from appearing in search results.
I need to disable code search entirely
If you need to turn off code search for all of your Bitbucket Server (or Data Center) users, you can disable code search entirely from within the bitbucket.properties file. See the page Bitbucket Server config properties - Search for details.
Code search is unavailable
There are a few ways Elasticsearch may not have been configured properly. To troubleshoot the bundled version of Elasticsearch that comes with Bitbucket Server, the page Troubleshooting steps for Bitbucket Datacenter Code Search is a good place to start. If you're still stuck after looking at the tips on that page, you could post a question in the Atlassian Community (in case your configuration is not typical or unsupported), or contact Atlassian Support for assistance (you'll need to log in to raise a support request).
Is Elasticsearch/code search required to run Bitbucket Server/Data Center?
Yes. Elasticsearch is required to run Bitbucket Server and Data Center (although code search can be disabled entirely if needed).
Can I use the bundled instance of Elasticsearch with Bitbucket Data Center?
No. Bitbucket Data Center requires a remote Elasticsearch instance, as it is not bundled or installed for Bitbucket Data Center.
Can I use a clustered installation of Elasticsearch with Bitbucket Data Center?
Yes, however, Bitbucket Data Center can have only one remote connection to Elasticsearch for your cluster. This may be a standalone Elasticsearch installation or a clustered installation behind a load balancer. For guidance on using a clustered Elasticsearch installation with Bitbucket Data Center, see the page Install and configure a remote Elasticsearch server, but note that Atlassian cannot guarantee support for such a setup in event you encounter problems.
How do I secure my remote Elasticsearch instance?
Atlassian strongly recommends you secure access to your remote Elasticsearch instance with a username and password, and a minimum of basic HTTP authentication. You can secure your remote Elasticsearch instance with a security plugin that requires anyone connecting to it provides authentication credentials. Atlassian provides a free plugin called Buckler for this purpose.
For instructions on how to secure your remote Elasticsearch instance with Buckler, see Install and configure a remote Elasticsearch instance - Secure your remote Elasticsearch instance.