When GitLab advanced search needs its own search cluster
Advanced search is a Premium and Ultimate feature that depends on a separate Elasticsearch or OpenSearch cluster, so a self-managed GitLab team that wants search across more than basic project and code lookups has to plan for a second stateful system before enabling it. The cluster is not a GitLab component you can turn on inside the application server. It is an external service that GitLab indexes and queries, and it carries its own hardware, storage, security and upgrade obligations. Teams should decide early whether they need it, because the decision changes the infrastructure budget, the tier conversation and the maintenance calendar.
The feature matters when developers and reviewers need to search across code, issues, merge requests, commit messages and comments at a scale that basic search does not serve well, or when the instance holds many projects and long histories. Teams should confirm the scopes they actually need with the GitLab advanced search documentation, because some code search needs are met by other tools. Before committing, check the current tier in the GitLab pricing page, confirm that your GitLab version supports the search engine versions you plan to run, and estimate cluster size with the estimate_cluster_size Rake task, which uses repository size as its input. Those answers determine whether the cluster is a small addition or a sizable service in its own right.
Choosing between Elasticsearch and OpenSearch for GitLab
This table compares Elasticsearch and OpenSearch as the search backend for GitLab advanced search across licensing, security features in free tiers, version lifecycle and operational fit. Read each row against your license policy, your security requirements and the GitLab version you plan to run, then confirm the items in the last column before you choose.
| Decision factor | Elasticsearch | OpenSearch |
|---|---|---|
| Licensing | Default distribution under Elastic License 2.0, with SSPL 1.0 and AGPLv3 also available; ELv2 and SSPL are not OSI-approved. Confirm which license your legal team accepts. | All software released under Apache License, Version 2.0, with no paid edition described. Confirm the license terms against your internal open-source policy. |
| Security features in free tiers | TLS, file and native user realms and role-based access control are free in the Basic tier. Confirm single sign-on and field- or document-level security tier needs with Elastic. | TLS, role-based access control, document- and field-level security, field masking and audit logs are part of the Security plugin. Confirm the authentication backends you need, such as SAML or LDAP. |
| Version support for GitLab | GitLab 19.1 and later supports Elasticsearch 8.x and 9.x. Elasticsearch 7.x support is deprecated in GitLab 18.10 and planned for removal in GitLab 20.0. | GitLab 19.1 and later supports OpenSearch 1.x and later. Confirm the exact OpenSearch line against the GitLab advanced search docs before you install. |
| Version lifecycle | Elastic publishes end-of-maintenance dates per release line, including 8.x and 9.x dates on the Elastic EOL page. Confirm dates before planning an upgrade. | OpenSearch releases a new minor about every eight weeks and maintains each version until the next major enters maintenance or one year passes. Confirm the maintenance window for your chosen line. |
| Packaging and deployment | Self-managed packages, Elastic Cloud and the Elastic Cloud on Kubernetes operator. ECK is offered in Basic and Enterprise tiers. Confirm which tier your Kubernetes plan needs. | Docker, Helm, the OpenSearch Kubernetes Operator, tarball, RPM, Debian packages and an Ansible playbook. Confirm which method your platform team already runs. |
| Managed cloud option | Elastic Cloud is Elastic's hosted service. Confirm region, data residency and whether GitLab's connection pattern works with your network controls. | Amazon OpenSearch Service runs OpenSearch in AWS with IAM-based access. Confirm IAM roles, VPC placement and the GitLab version compatibility before you choose it. |
| Operational fit | Choose it when your team already runs Elastic components and has an existing support or subscription relationship. Confirm the node roles and three master-eligible nodes for a highly available cluster. | Choose it when you want an Apache 2.0 stack under a foundation-governed project. Confirm the cluster sizing, at least two nodes with one replica, and SSD storage that GitLab recommends. |
| Migration path | Moving between Elasticsearch versions requires index and version checks. Confirm the upgrade order and any reindexing GitLab needs after a version change. | OpenSearch can use indices from Elasticsearch 6.0 through 7.10 and supports rolling upgrades from those versions. Confirm GitLab reindexing requirements before switching engines. |
Running the search cluster on Amazon OpenSearch Service with IAM
Amazon OpenSearch Service runs OpenSearch as an AWS-managed service, so AWS operates the domain infrastructure while your team still owns the GitLab integration, the index state and the decision to turn search on. This split changes what you plan. Patching and node replacement are handled by the service, but cluster sizing and reindexing still depend on your repository volume and on the sizing guidance GitLab documents for self-managed instances.
- Who operates what: AWS manages the domain hosts and the OpenSearch software on them, while your team manages GitLab settings, index state and access policy.
- Sizing still applies: GitLab recommends at least two nodes with one replica, SSD storage and a heap of no more than 50% of RAM. Confirm these map onto the instance types and storage options you select.
- Cost components: Expect recurring charges for domain instances, storage and data transfer, plus one-time effort to build the integration. Ask any partner to separate setup from recurring service charges in the quote.
- Separate component: The search cluster is a service distinct from GitLab, so give it its own monitoring, capacity review and change process.
Check the service's current version list and node options against the GitLab advanced search docs before you choose a domain size.
IAM-based access means GitLab authenticates its requests to the domain with AWS identities instead of a shared username and password. The exact mechanism GitLab uses to sign those requests, and which AWS identity types it accepts, is defined in the advanced search docs and must be confirmed for your GitLab version before the design is final.
- Identity for GitLab: Decide whether GitLab reaches the domain through an instance role, a dedicated IAM user or another identity, then confirm which of these your GitLab release accepts.
- Least privilege: Scope the policy to the one domain and to the index actions GitLab needs. Avoid broad wildcard resources.
- Policy interaction: Confirm how the domain access policy and any fine-grained access control interact with IAM principals, since both can allow or deny the same request.
- Admin separation: Keep the people who administer the domain apart from the identity GitLab uses to read and write indices.
- Credential rotation: Confirm how rotation works for the chosen identity and whether GitLab needs a restart or reconfiguration when credentials change.
Before go-live, test the identity against a non-production index and record the denied-request behavior so the access policy has evidence behind it.
Network placement decides who can reach the domain at all. Plan whether the domain is reachable only inside a VPC, which subnets and security groups the GitLab hosts use, and how administrators reach the domain for troubleshooting. The supplied guidance does not define the VPC options for the managed service, so confirm them with AWS documentation and the GitLab advanced search docs.
- Private placement: Keep the domain in private subnets reachable only from the GitLab hosts that need search.
- Security groups: Allow HTTPS only from the GitLab application and Sidekiq hosts that need search, and document each rule for audit.
- Availability zones: Spread nodes across zones where the service supports it, since GitLab recommends at least two nodes with one replica.
- Runner access: Confirm that CI runners do not need direct network access to the search cluster.
- Name resolution and egress: Plan DNS resolution for the domain endpoint and any proxy rules, especially in restricted or air-gapped egress networks.
Confirm the network path with a connection test from each GitLab role before indexing starts, because a blocked path can look like a search fault.
Version pairing has two checks. The GitLab release you run must support the OpenSearch line you choose, and that OpenSearch line must still receive fixes. GitLab 19.1 and later supports Elasticsearch 8.x and 9.x and OpenSearch 1.x and later, and Elasticsearch 7.x support is deprecated in 18.10 and planned for removal in 20.0. OpenSearch 1 reached end of life on May 6, 2025, so a new domain should not start on that line even though GitLab accepts it.
- GitLab version first: Confirm the GitLab release you run supports the OpenSearch version the managed service offers.
- Avoid end-of-life lines: Choose an OpenSearch line still in maintenance, and check the OpenSearch releases page for current status.
- Coordinate upgrades: Plan domain version upgrades and GitLab upgrades in separate change windows, and check GitLab's required upgrade stops first.
- Track the deprecation: If Elasticsearch 7.x is in use, plan its move before removal in 20.0.
- Check offered versions: A version can be offered by the managed service yet be unsupported by GitLab, so compare the two lists directly.
Record the GitLab version, the domain version and the date you checked the support list in your change record.
Sizing the cluster from repository size and user load
Start sizing with the estimate_cluster_size Rake task in the GitLab installation, because it derives a starting cluster size from your repository volume rather than from guesswork. GitLab recommends running the search cluster on separate servers from the GitLab application, with at least two nodes and one replica of each index, on SSD storage, and with the JVM heap set to no more than 50% of available RAM. Treat these as the floor for a production cluster, then confirm the current wording in the GitLab advanced search documentation before you order hardware, since the requirements are tied to the GitLab release you run.
Several factors push the cluster larger. Repository volume is the main driver, and the size of the Git data you index matters more than the number of users. Indexing scope also matters: every additional data type you index, such as issues, merge requests, comments and code blobs, adds storage and indexing work. Replica count is the third lever, because each replica doubles the stored data for that index and adds write load on the cluster. Ask your team to measure the repository footprint and the planned indexing scope, then run the Rake task against those figures instead of sizing from the total user count alone.
Plan node roles with availability in mind. A highly available Elasticsearch or OpenSearch cluster needs at least three master-eligible nodes, so a two-node data layout still requires a third node that votes in cluster decisions, even if it holds no data. Confirm with the vendor documentation for your chosen engine and version how dedicated master nodes should be placed, and check that the OpenSearch or Elasticsearch version you select is supported by your GitLab release before you build the cluster.
Indexing order before you turn advanced search on
This sequence moves a self-managed GitLab instance from a confirmed tier and supported search versions to a healthy, fully indexed cluster. Each step closes with a check, so search is enabled only after the index is verified.
Confirm tier and supported search versions
Confirm that your GitLab edition and tier include advanced search, which the documentation lists as a Premium and Ultimate feature. Then match your GitLab version to a supported engine: GitLab 19.1 and later support Elasticsearch 8.x and 9.x and OpenSearch 1.x and later, and Elasticsearch 7.x support is deprecated in 18.10 and planned for removal in 20.0. Check that your GitLab version and engine version appear together in the advanced search documentation. Done means you have a written version pair approved by the platform owner.
Deploy the search cluster on separate servers
Provision the search cluster on servers separate from GitLab itself, with at least two nodes and one replica, and use SSD storage as GitLab recommends. Set the JVM heap to no more than 50% of RAM. Confirm that the nodes can reach each other and the GitLab application servers on the required ports, and that the cluster reports green or yellow health with the expected node count. Done means the cluster answers health requests from the GitLab network segment.
Size the cluster with estimate_cluster_size
Run the estimate_cluster_size Rake task on the GitLab instance to derive cluster sizing from your repository footprint. Compare its output with the node count and storage you deployed in the previous step, and record any gap for the capacity owner to resolve before indexing. Ask your architect whether your user count and CI load also call for a larger reference architecture. Done means the sizing output is saved alongside the deployed capacity, with any shortfall documented.
Configure TLS and authentication on the cluster
Enable TLS for node and client traffic and create a dedicated service account for GitLab with the least privileges needed to manage indices. For OpenSearch, confirm which Security plugin authentication backend and role mappings you will use, and for Amazon OpenSearch Service, confirm how IAM access is granted to the GitLab hosts. Verify with a test request from a GitLab host that TLS negotiates correctly and that the service account authenticates while an unauthenticated request is refused. Done means both checks pass and the credentials are stored in your secrets manager.
Connect GitLab to the search cluster
In the Admin area, add the cluster URL and credentials for advanced search, but keep indexing paused until the next steps are complete. Confirm the connection settings are saved and that GitLab reports the cluster as reachable. Check the GitLab logs for connection errors after saving. Done means GitLab shows a successful connection while search remains off for end users.
Run the initial indexing
Start the initial indexing run for the instance, using the Rake task or the administration option described in the advanced search documentation. Indexing runs against the whole instance, so schedule it for a window agreed with the platform team, and monitor the GitLab logs and Sidekiq queues for failures and retries. Confirm that the indexing job reports completion before moving on. Done means the job finishes with no unresolved errors in the logs.
Verify index health before enabling search
Check cluster health, shard allocation, document counts and disk usage against the sizing record from the earlier step. Compare the document counts with what GitLab reports for projects, and run a few test searches for known code and issue text from different groups. Confirm that the cluster has no unassigned shards and that heap usage stays within the limit you set. Done means the counts match, the test searches return expected results and the cluster is stable.
Enable advanced search for users
Turn on advanced search in the GitLab Admin area only after the verification passes. Run a final set of searches as a standard user with the permissions you expect, and confirm that results respect project visibility and access. Record the enablement date, the engine and GitLab versions, and the sizing output in your change record. Done means users see only the results their permissions allow and the change record is complete.
Securing the search cluster and its credentials
A search cluster holds an index of your source code, issues and merge requests, so it needs the same access discipline as the GitLab instance that feeds it. The cards below cover the controls that decide who can read that index, how traffic is protected and where the cluster can be reached from. Confirm each configuration path against the exact product version you deploy.
Encrypt node and client traffic
Enable TLS for traffic between cluster nodes and for connections from GitLab to the cluster, so repository-derived content is not readable on the network. Both Elasticsearch and OpenSearch support TLS for these paths, and OpenSearch Security lists it as a core feature. Check that GitLab trusts the correct certificate authority and that certificate renewal is part of your operations runbook, because an expired certificate stops indexing and search.
Scope access with role-based control
Create a dedicated service user for GitLab with the narrowest index permissions that let it write and query the GitLab indices, and keep administrative accounts separate. Both products provide role-based access control, and OpenSearch Security also offers document-level and field-level security and field masking. Confirm which of these controls your chosen edition and license include before you design the role model.
Match authentication to your identity provider
List the authentication backends each product supports before choosing one for human administrators. OpenSearch Security supports SAML, OpenID Connect, Active Directory and LDAP, Kerberos and JSON Web Token. Elastic's subscription page lists single sign-on for SAML, OpenID Connect, Kerberos and JWT, and places some of these features in paid tiers. Confirm the license level for each backend in your version.
Keep audit trails on administrative actions
Turn on audit logging so changes to roles, users, index settings and cluster configuration are recorded, and ship those logs to the store your security team reviews. OpenSearch Security includes audit logs. For Elasticsearch, confirm whether audit logging sits in the tier you license, because feature availability differs by subscription. Test that an administrative change produces a log entry before you rely on it.
Keep the cluster off public networks
Place the search cluster on a private subnet reachable only from the GitLab application and its administrators, with firewall rules that block direct internet access. GitLab's own guidance recommends running the search cluster on separate servers, so treat that network boundary as part of the design. Verify the exposure with an external scan after each change, and record which hosts can reach ports used for cluster and client traffic.
Protect the credentials GitLab stores
Store the search user password and any API keys in a secrets store that your GitLab administrators control, and rotate them on a schedule your team can execute. Restrict who can change the search integration settings in GitLab, because those settings hold the connection details. Rotation must update both the cluster and GitLab, so document the sequence and test it in a non-production environment first.
Limits to confirm in your environment
Advanced search depends on version pairs, a search cluster lifecycle and index work that all move on their own schedules. The cards below list what to confirm against your GitLab release and your own repositories before you choose a search engine version or set a date for enabling search.
Supported versions for your release
GitLab 19.1 and later supports Elasticsearch 8.x and 9.x and OpenSearch 1.x and later. Confirm the exact pairing for the GitLab release you plan to run, because support is defined per GitLab version and search engine line. Check the advanced search documentation before you pick a cluster version, and recheck it at each GitLab upgrade stop, since your target release may narrow or widen the list.
Elasticsearch 7.x removal in 20.0
Elasticsearch 7.x support is deprecated in GitLab 18.10 and planned for removal in GitLab 20.0. If your instance runs a 7.x cluster, the migration to a supported version is a dated task that must be scheduled alongside your major upgrade path. Ask GitLab support or your DeployOpen contact to confirm the removal timing for your target release before you plan the cutover.
Elastic end-of-life dates by line
Elastic publishes end-of-maintenance dates per release line, and they differ between 8.x and 9.x. Check the Elastic end-of-life page for the exact line you deploy, then compare those dates with your GitLab support window. A cluster line that ends maintenance before your next planned upgrade will need a version change sooner than expected, so record the dates in your change calendar.
Index size and reindex time
Indexing the instance is required before search is enabled, and the work scales with repository content. Run the estimate_cluster_size Rake task against your own repositories to size storage and nodes, then time a full index on a copy of production data. Measured reindex time, not a generic estimate, should set your go-live window and tell you how long the instance runs with incomplete search results.
Scopes covered by advanced search
Advanced search covers scopes such as code, commits, issues and merge requests, but not every search type. Exact match and regex code search is handled by Zoekt in some setups, so list the search scopes your teams rely on and confirm which tool serves each one. Gaps found here change whether you need a second search component, extra storage or a Zoekt deployment, so resolve them before design sign-off.
Tier and licensing fit
Advanced search is a Premium and Ultimate feature, so a Free instance cannot use it regardless of the search cluster you build. Confirm your license tier and whether your search engine edition needs a paid subscription, because Elastic's default distribution uses the Elastic License 2.0 while OpenSearch is released under Apache License 2.0. Get both answers in writing before you commit to a platform.
What teams ask before running advanced search
What does advanced search cost on self-managed GitLab?
Advanced search needs a GitLab Premium or Ultimate subscription, so the largest recurring line is usually the license. The GitLab pricing page lists Premium at 29 US dollars per user per month billed annually, and Ultimate is custom priced. The search cluster adds hosting cost that recurs in your cloud account or data center: separate servers, at least two nodes with one replica, and SSD storage. Setup effort and operations staff time are the other components. In a quote, ask for one-time work (design, build, indexing, validation, handover) listed separately from recurring work (monitoring, patching, upgrades, support), with node counts and storage stated.
How long does advanced search setup take for our repositories?
Duration depends mainly on how much repository content must be indexed and how long indexing takes on your cluster, so no fixed figure applies. GitLab recommends indexing the instance before enabling search, which makes indexing the step to plan around. The estimate_cluster_size Rake task sizes the cluster from repository size, so run it against your real data before you commit to a schedule. Ask for a timeline tied to that measured size, the number of environments to validate, and the approval windows in your change process. Cluster build normally comes before GitLab configuration, because the search settings depend on a working cluster.
Should we choose Elasticsearch or OpenSearch for GitLab?
Choose OpenSearch if you want a search engine under the Apache License, Version 2.0, since its FAQ does not describe any paid edition. GitLab 19.1 and later support Elasticsearch 8.x and 9.x and OpenSearch 1.x and later, so both are possible on current releases. Elasticsearch 7.x support is deprecated in GitLab 18.10 and planned for removal in 20.0, so avoid starting new work on it. Elastic's default distribution uses the Elastic License 2.0, which is not an OSI-approved open source license. Confirm the supported versions for your target GitLab release, the features your team needs, and the vendor's support dates for the line you pick.
What must our team provide before the search cluster starts?
You provide the infrastructure, the GitLab Premium or Ultimate license, the target versions and the network paths. For the cluster, that means separate servers or cloud instances, SSD storage sized from repository volume, at least two nodes with one replica, and a heap no larger than 50% of RAM. You also need network access from GitLab to the cluster, certificate and credential handling, and a named owner for backups and patching. Share repository size and user counts so the sizing task can run on real figures. For Amazon OpenSearch Service with IAM, confirm in GitLab's documentation which IAM and endpoint settings your GitLab version supports before you commit to that model.
Can our own team set up advanced search without a partner?
Yes, if your team already runs GitLab and a search cluster and has capacity to operate both. The official documentation covers the steps, and the sequence is: size the cluster, provision nodes, configure the GitLab search integration, index the instance, then enable search. The harder parts are sizing for real repository volume, securing the cluster, and keeping it aligned through GitLab and search upgrades. A partner can take that work under a written, fixed scope. DeployOpen plans and implements self-hosted platforms inside your own infrastructure and documents the result for handover, with scope and price set by a quote.
How do GitLab upgrades affect the search cluster?
Treat the GitLab upgrade and the search cluster upgrade as one change, and test both together in staging. GitLab requires upgrade stops, which since 17.5 fall at versions x.2, x.5, x.8 and x.11, such as 18.2, 18.5, 18.8, 18.11, 19.2, 19.5, 19.8 and 19.11. Each target release can change the supported search engine versions, so check that range in the GitLab documentation before changing either side. The search engine has its own lifecycle: OpenSearch targets a new minor version about every eight weeks, and Elastic publishes end of maintenance dates for each line. Plan rolling upgrades of the cluster and confirm whether the index must be rebuilt after a version change.
What usually goes wrong in advanced search deployments?
The most common problems are a cluster sized from guesses, indexing that runs longer than planned, and search turned on before indexing is complete. GitLab recommends indexing the instance before enabling search, so early enablement produces incomplete results and rework. Undersized heap, missing replicas and slow storage tend to surface under load, after users start searching. Put monitoring on cluster health, disk use and index growth from day one. Confirm with GitLab's backup documentation whether the search index is included in backups or must be rebuilt, and rehearse that recovery path before production use.
What should a quote for advanced search include?
A useful quote states the scope in writing: the GitLab edition and user count, the search engine and version, the hosting model, node count and storage, the environments to build, and the indexing and cutover plan. Ask for one-time costs separately from recurring work such as monitoring, patching, upgrades and support. Ask which items the quote assumes from your side, including infrastructure, network access and an owner for the cluster. DeployOpen issues fixed-scope quotes from a written scope, so you can compare the offer with the cost of running the work internally.
How the scope of a search implementation is agreed
DeployOpen agrees the scope, deliverables and timeline of an advanced search implementation in writing before any work starts. The written scope should name the GitLab tier, since advanced search is a Premium and Ultimate feature, and the search product and version. For the product, confirm whether you intend Elasticsearch or OpenSearch and which major line, because GitLab 19.1 and later supports Elasticsearch 8.x and 9.x and OpenSearch 1.x and later, and Elasticsearch 7.x support is deprecated in 18.10 and planned for removal in 20.0. Confirm the current compatibility list for your exact GitLab version with the advanced search documentation before the scope is signed.
The scope should also record the hosting model and the sizing inputs. Name where the search cluster will run (your data center, your cloud account or an Amazon OpenSearch Service domain with IAM access), whether the nodes will be separate from GitLab servers, and the storage type. Sizing inputs include total repository size, which feeds the estimate_cluster_size Rake task, the number of nodes with at least one replica, and the heap limit of no more than 50% of RAM. Write down who supplies each input, because an unmeasured repository size is the most common reason a sizing estimate changes after the work has begun.
Finally, the written scope should describe the indexing plan and the verification steps. Specify that the instance will be indexed before search is enabled, how long indexing is expected to run on your data (to be estimated during planning, not assumed), who approves the switch-over, and which checks confirm success, such as search results matching a set of test queries and access rules holding for users in different groups. Also agree what happens to Elasticsearch 7.x deployments and how upgrades of the search cluster are handled after go-live, since these recur and belong in the scope rather than in a later change request.
How DeployOpen works on this
DeployOpen plans, builds and documents GitLab advanced search inside your own infrastructure, from the choice between Elasticsearch and OpenSearch to the indexing order that runs before search is turned on. Engagements are fixed-scope, so the search version, cluster layout and handover items are agreed in writing before work starts.
How we scope
- Confirm your GitLab edition and tier, since advanced search requires Premium or Ultimate.
- Record the supported Elasticsearch or OpenSearch version against the GitLab release you run.
- Size the search cluster from repository volume using the estimate_cluster_size Rake task output.
- Agree in writing whether the search cluster is self-hosted or Amazon OpenSearch Service with IAM.
How we build
- Deploy the search cluster on separate servers with at least two nodes and one replica.
- Configure TLS, authentication and role-based access before GitLab connects to the cluster.
- Set heap size to no more than half of available RAM and place data on SSD storage.
- Run the initial indexing and confirm index completion before enabling advanced search.
How we hand over
- Deliver a runbook covering cluster sizing, index rebuild steps and version compatibility notes.
- Document the indexing order, reindexing triggers and the procedure for changing scope.
- Walk your administrators through backup, snapshot and restore of search indices alongside GitLab backups.
- Provide a test record showing search results and access controls verified in your environment.
How we support
- Plan the search version upgrade alongside GitLab upgrade stops and Elasticsearch or OpenSearch maintenance dates.
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- Confirm with your vendor and your own environment which search versions remain supported at each stage.
