Search contexts

This feature is only available with an active Enterprise license. Please add your license key to activate it.

A search context is a user-defined grouping of repositories that helps focus searches on specific areas of your codebase, like frontend, backend, or infrastructure code. Some example queries using search contexts:

• context:data_engineering userId - search for userId across all repos related to Data Engineering.
• context:k8s ingress - search for anything related to ingresses in your k8’s configs.
• ( context:project1 or context:project2 ) logger\.debug - search for debug log calls in project1 and project2

Search contexts are defined in the context object inside of a declarative config. Repositories can be included / excluded from a search context by specifying the repo’s URL in either the include array or exclude array. Glob patterns are supported.

Example

Let’s assume we have a GitLab instance hosted at https://gitlab.example.com with three top-level groups, web, backend, and shared:

web/
├─ admin_panel/
├─ customer_portal/
├─ pipelines/
├─ ...
backend/
├─ billing_server/
├─ auth_server/
├─ db_migrations/
├─ pipelines/
├─ ...
shared/
├─ protobufs/
├─ react/
├─ pipelines/
├─ ...

To make searching easier, we can create three search contexts in our config.json:

• web: For all frontend-related code
• backend: For backend services and shared APIs
• pipelines: For all CI/CD configurations

{
    "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json",
    "contexts": {
        "web": {
            // To include repositories in a search context,
            // you can reference them...
            "include": [
                // ... individually by specifying the repo URL.
                "gitlab.example.com/web/admin_panel/core",


                // ... or as groups using glob patterns. This is
                // particularly useful for including entire "sub-folders"
                // of repositories in one go.
                "gitlab.example.com/web/customer_portal/**",
                "gitlab.example.com/shared/react/**",
                "gitlab.example.com/shared/protobufs/**"
            ],

            // Same with excluding repositories.
            "exclude": [
                "gitlab.example.com/web/customer_portal/pipelines",
                "gitlab.example.com/shared/react/hooks/**",
            ],

            // Optional description of the search context
            // that surfaces in the UI.
            "description": "Web related repos."
        },
        "backend": { /* ... specifies backend replated repos ... */},
        "pipelines": { /* ... specifies pipeline related repos ... */ }
    },
    "connections": {
        /* ...connection definitions... */
    }
}

Repository URL details

Repo URLs are expected to be formatted without the leading http(s):// prefix. For example:

• github.com/sourcebot-dev/sourcebot (link)
• gitlab.com/gitlab-org/gitlab (link)
• chromium.googlesource.com/chromium (link)

Once configured, you can use these contexts in the search bar by prefixing your query with the context name. For example:

• context:web login form searches for login form code in frontend repositories
• context:backend auth searches for authentication code in backend services
• context:pipelines deploy searches for deployment configurations

Like other prefixes, contexts can be negated using - or combined using or:

• -context:web excludes frontend repositories from results
• ( context:web or context:backend ) searches across both frontend and backend code

See this doc for more details on the search query syntax.

Schema reference

Reference

schemas/v3/searchContext.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "SearchContext",
  "description": "Search context",
  "properties": {
    "include": {
      "type": "array",
      "description": "List of repositories to include in the search context. Expected to be formatted as a URL without any leading http(s):// prefix (e.g., 'github.com/sourcebot-dev/sourcebot'). Glob patterns are supported.",
      "items": {
        "type": "string"
      },
      "examples": [
        [
          "github.com/sourcebot-dev/**",
          "gerrit.example.org/sub/path/**"
        ]
      ]
    },
    "exclude": {
      "type": "array",
      "description": "List of repositories to exclude from the search context. Expected to be formatted as a URL without any leading http(s):// prefix (e.g., 'github.com/sourcebot-dev/sourcebot'). Glob patterns are supported.",
      "items": {
        "type": "string"
      },
      "examples": [
        [
          "github.com/sourcebot-dev/sourcebot",
          "gerrit.example.org/sub/path/**"
        ]
      ]
    },
    "description": {
      "type": "string",
      "description": "Optional description of the search context that surfaces in the UI."
    }
  },
  "required": [
    "include"
  ],
  "additionalProperties": false
}