Semantic code search

  • Tier: Premium, Ultimate
  • Add-on: GitLab Duo Core, Pro, or Enterprise
  • Offering: GitLab.com, GitLab Self-Managed
  • Status: Beta

Semantic code search uses AI to find relevant code snippets in your repository based on meaning rather than keyword matching.

Semantic code search converts your codebase into vector embeddings and stores these embeddings in a vector database. Your search query is also converted into an embedding and then compared against your code embeddings to find the most semantically similar results. This approach finds relevant code even when keywords do not match.

Improvements to this feature are proposed in epic 18018 and epic 20110.

Prerequisites

  • Access to the GitLab-operated AI Gateway.
  • These features turned on:
    • For GitLab.com, experiment features for your top-level group.
    • For GitLab Self-Managed, GitLab Duo experiment and beta features for the instance.
  • GitLab Duo turned on for your project.
  • One of these vector stores configured:
    • Elasticsearch 8.0 and later.
    • OpenSearch 2.0 and later.
    • PostgreSQL with the pgvector extension.
  • Administrator access.

With the UI

If your GitLab instance uses Elasticsearch or OpenSearch for advanced search, you can enable semantic code search by connecting to the same cluster:

  1. In the upper-right corner, select Admin.
  2. Select Settings > Search.
  3. Expand Semantic search.
  4. Select Connect to the advanced search cluster.

With the Rails console

To create a custom vector store connection for Elasticsearch, OpenSearch, or PostgreSQL, in the Rails console, create a connection with adapter and options.

You should use Elasticsearch or OpenSearch for medium to large repositories. Use PostgreSQL with pgvector only for setups with a few small repositories. Indexing and querying performance might be limited with pgvector.

Elasticsearch

connection = Ai::ActiveContext::Connection.create!(
  name: "elasticsearch",
  options: options,
  adapter_class: "ActiveContext::Databases::Elasticsearch::Adapter"
)
connection.activate!

Connection options:

Option Type Required Default Description
url array of strings Yes None Array of URLs for your Elasticsearch cluster (for example, ["http://localhost:9200"]).
client_adapter string No typhoeus HTTP adapter to use. Possible values are typhoeus and net_http.
client_request_timeout integer No 30 Request timeout in seconds.
retry_on_failure integer No 0 Number of retries on failure.
debug boolean No false Enables debug logging.

OpenSearch

connection = Ai::ActiveContext::Connection.create!(
  name: "opensearch",
  options: options,
  adapter_class: "ActiveContext::Databases::Opensearch::Adapter"
)
connection.activate!

Connection options:

Option Type Required Default Description
url array of strings Yes None Array of URLs for your OpenSearch cluster (for example, ["http://localhost:9200"]).
client_adapter string No typhoeus HTTP adapter to use. Possible values are typhoeus and net_http.
client_request_timeout integer No 30 Request timeout in seconds.
retry_on_failure integer No 0 Number of retries on failure.
debug boolean No false Enables debug logging.
aws boolean No false Enables AWS Signature Version 4 signing.
aws_region string No None AWS region for your OpenSearch domain.
aws_access_key string No None AWS access key ID.
aws_secret_access_key string No None AWS secret access key.

PostgreSQL with pgvector

For PostgreSQL, use the pgvector extension:

  1. In the PostgreSQL database, create the extension:

    CREATE EXTENSION vector;

  2. In the Rails console, create the connection:

    connection = Ai::ActiveContext::Connection.create!(
  name: "postgres",
  options: options,
  adapter_class: "ActiveContext::Databases::Postgresql::Adapter"
)
connection.activate!

Connection options:

Option Type Required Default Description
host string Yes None PostgreSQL host.
port integer No None PostgreSQL port.
database string No None Database name.
user string No None PostgreSQL user.
password string No None PostgreSQL password.
connect_timeout integer No 5 Connection timeout in seconds.
pool_size integer No 5 Connection pool size.

Semantic code search is available as a GitLab MCP server tool. For more information about how to use this tool, see semantic_code_search.

When you first use semantic code search in a GitLab project:

  • Your repository code is indexed and converted into vector embeddings.
  • These embeddings are stored in your configured vector store.
  • Updates are processed incrementally when code is merged to the default branch.

Initial indexing might take a while depending on your repository size.