Semantic code search administration

{{< details >}}

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

{{< /details >}}

{{< history >}}

• Introduced as a beta in GitLab 18.7.
• Added to GitLab Duo Core in GitLab 18.8.
• Added to GitLab Premium in GitLab 18.9.

{{< /history >}}

[!note] For user documentation, see semantic code search.

With semantic code search, AI-native GitLab Duo features can find relevant code snippets in your repository.

Prerequisites

• Access to the GitLab AI Gateway or GitLab Duo Self-Hosted.
• Beta and experimental features turned on for the instance.
• A vector store configured:
  • Elasticsearch 8.0 and later.
  • OpenSearch 2.0 and later.
  • PostgreSQL with the pgvector extension.
• For GitLab Duo Self-Hosted, an embedding model configured.

Vector storage

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.

Connect to the advanced search cluster

{{< history >}}

• Introduced in GitLab 18.7.

{{< /history >}}

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

1. In the upper-right corner, select Admin.
2. In the left sidebar, select Settings > Search.
3. Expand Semantic search.
4. For Vector storage, select Configure.
5. On the Vector storage page, under Advanced search cluster, select Connect.

Configure a custom vector store

{{< history >}}

• Introduced in GitLab 19.2.

{{< /history >}}

To configure a custom vector store connection:

1. In the upper-right corner, select Admin.
2. In the left sidebar, select Settings > Search.
3. Expand Semantic search.
4. For Vector storage, select Configure.
5. From the Search adapter dropdown list, select Elasticsearch, OpenSearch, or PostgreSQL.
6. Complete the fields for your adapter.
7. Select Save changes.

Elasticsearch

OpenSearch

To use AWS OpenSearch Service, select Use AWS OpenSearch Service with IAM credentials and complete the fields:

PostgreSQL with pgvector

Prerequisites:

• Enable the pgvector extension in your PostgreSQL database:

  sqlCopy

  CREATE EXTENSION vector;
  

Configure an embedding model

To configure an embedding model:

1. In the upper-right corner, select Admin.
2. In the left sidebar, select Settings > Search.
3. Expand Semantic search.
4. For Code embeddings, select Set model. If you already configured an embedding model, Change model appears instead.
5. On the Semantic search code embeddings page, select the embedding model, embedding dimensions, and the chunking strategy.
6. Select Set embeddings. If you already configured an embedding model, Update embeddings and start backfill process appears instead.

[!warning] When you change the embedding model or dimensions, a backfill runs that can take several hours depending on your codebase size. Semantic search remains available during this process.

Embedding models

GitLab-managed models

{{< history >}}

• Introduced in GitLab 19.0 with a feature flag named semantic_search_user_model_selection. Disabled by default.

{{< /history >}}

[!flag] The availability of this feature is controlled by a feature flag. For more information, see the history.

Prerequisites:

• Access to both the GitLab AI Gateway and GitLab Duo Self-Hosted.

GitLab-managed models are offered on the GitLab AI Gateway. Select the text-embedding-005 model provided by the Gemini Enterprise Agent Platform.

For more information about GitLab-managed models with a GitLab Duo Self-Hosted setup, see hybrid AI Gateway and model configuration.

[!warning] If GitLab deprecates a model you selected, you must switch to a different model yourself.

Self-hosted models

{{< history >}}

• Introduced in GitLab 19.1 with a feature flag named semantic_search_user_model_selection. Disabled by default.

{{< /history >}}

[!flag] The availability of this feature is controlled by a feature flag. For more information, see the history.

Prerequisites:

• Access to GitLab Duo Self-Hosted.
• Self-hosted beta models and features turned on.

Self-hosted models are AI models hosted on your own infrastructure.

To select a self-hosted model:

1. Set up GitLab Duo Self-Hosted.
2. Add a self-hosted model with an EMBEDDING model family.

Chunking strategy

{{< history >}}

• Introduced in GitLab 19.2 with a feature flag named semantic_search_user_model_selection. Disabled by default.

{{< /history >}}

[!flag] The availability of this feature is controlled by a feature flag. For more information, see the history.

The chunking strategy is the algorithm used to split code files into smaller snippets for embeddings. Select one of the following strategies:

• Code bytes: Splits code into fixed-size byte chunks without considering code structure or semantics. Chunk size refers to the maximum number of bytes per chunk. Use this strategy for the following:
  • Faster indexing and more predictable chunk size.
  • Repositories with diverse file types and languages.
• Code pre-BERT: Splits code by using semantic boundaries optimized for BERT-based embedding models. Chunk size refers to the maximum number of tokens per chunk. Use this strategy for the following:
  • Better search quality and more meaningful chunks that respect code structure.
  • Repositories with well-structured code.

[!warning] You can select the chunking strategy only when you configure the embedding model for the first time. To change the chunking strategy after indexing starts, you must fully reindex the instance. Support for automatic reindexing is proposed in issue 600200 and issue 602138.

Check semantic code search status

{{< history >}}

• Introduced in GitLab 19.0.

{{< /history >}}

To check the status of semantic code search, including indexing status, vector store connection details, repository statistics, and embedding queue sizes, run this Rake task:

sudo gitlab-rake gitlab:semantic_search:code:info

To monitor status continuously, provide a watch interval in seconds:

sudo gitlab-rake "gitlab:semantic_search:code:info[5]"

This task refreshes the output at the specified interval. To stop the task, press <kbd>Control</kbd>+<kbd>C</kbd>.

Manage the dead queue

Prerequisites:

• A personal access token with the admin_mode, ai_features, and api scopes.

When embedding generation fails repeatedly, items are moved to the dead queue for manual intervention. You can check the dead queue size in the Embedding Queues section of the status Rake task output.

Clear the dead queue

To delete all items from the dead queue, run this command:

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_token>" \
  "https://gitlab.example.com/api/v4/admin/active_context/dead_queue"

Replay the dead queue

To move dead queue items back into a processing queue for another attempt, use the queue parameter to specify the target. Valid values are retry_queue, code, and code_backfill.

To attempt processing once more before potentially failing back to the dead queue, use retry_queue:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_token>" \
  --data "queue=retry_queue" \
  "https://gitlab.example.com/api/v4/admin/active_context/dead_queue/replay"

To add items to the main code queue, use code:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_token>" \
  --data "queue=code" \
  "https://gitlab.example.com/api/v4/admin/active_context/dead_queue/replay"