Skip to main content
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... */
    }
}
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
Example 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.

​
Filtering by topic

If your repositories are tagged with topics on GitHub or GitLab, you can use includeTopics and excludeTopics to filter repositories by topic instead of (or in addition to) specifying individual repo URLs. Glob patterns are supported. 
{
    "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json",
    "contexts": {
        "backend": {
            "includeTopics": ["backend", "core-*"],
            "excludeTopics": ["deprecated", "archived-*"],
            "description": "Active backend services."
        }
    },
    "connections": {
        /* ...connection definitions... */
    }
}
includeTopics and excludeTopics follow the same additive semantics as include and exclude:
  • includeTopics adds all repos tagged with a matching topic to the context.
  • excludeTopics removes repos tagged with a matching topic from the context.
  • Both can be freely combined with include, includeConnections, exclude, and excludeConnections.
Topic matching is case-insensitive, so "Backend" matches the pattern "backend".
Topics are populated when a connection syncs. If you add topics to your repositories after the last sync, trigger a re-sync for the new topics to take effect.

​
Schema 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/**"
        ]
      ]
    },
    "includeConnections": {
      "type": "array",
      "description": "List of connections to include in the search context.",
      "items": {
        "type": "string"
      }
    },
    "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/**"
        ]
      ]
    },
    "excludeConnections": {
      "type": "array",
      "description": "List of connections to exclude from the search context.",
      "items": {
        "type": "string"
      }
    },
    "includeTopics": {
      "type": "array",
      "description": "List of repository topics to include in the search context. Only repositories matching at least one topic are included. Glob patterns are supported.",
      "items": {
        "type": "string"
      },
      "examples": [
        [
          "backend",
          "core-*"
        ]
      ]
    },
    "excludeTopics": {
      "type": "array",
      "description": "List of repository topics to exclude from the search context. Repositories matching any of these topics are excluded. Glob patterns are supported.",
      "items": {
        "type": "string"
      },
      "examples": [
        [
          "deprecated",
          "archived-*"
        ]
      ]
    },
    "description": {
      "type": "string",
      "description": "Optional description of the search context that surfaces in the UI."
    }
  },
  "additionalProperties": false
}