---
title: Overview
sidebarTitle: Overview
---

import SupportedPlatforms from '/snippets/platform-support.mdx'
import ConfigSchema from '/snippets/schemas/v3/index.schema.mdx'

A **connection** in Sourcebot represents a link to a code host (such as GitHub, GitLab, Bitbucket, etc.). Each connection defines how Sourcebot should authenticate and interact with a particular host, and which repositories to sync and index from that host. Connections are uniquely identified by their name.

A JSON configuration file is used to specify connections. For example:

```json
// Specifies two connections:
{
    "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json",
    "connections": {
        // 1. A connection to GitHub.com
        "github-connection": {
            "type": "github",
            "repos": [
                "sourcebot-dev/sourcebot"
            ],
            "token": {
                "env": "GITHUB_TOKEN"
            }
        },
        // 2. A self-hosted GitLab instance
        "gitlab-connection": {
            "type": "gitlab",
            "url": "https://gitlab.example.com",
            "groups": [
                "my-group",
                "my-other-group/sub-group"
            ],
            "token": {
                "env": "GITLAB_TOKEN"
            }
        }
    }
}
```

Configuration files must conform to the [JSON schema](#schema-reference).

When running Sourcebot, this file must be mounted in a volume that is accessible to the container, with its path specified in the `CONFIG_PATH` environment variable. For example:

```bash
docker run \
    -v $(pwd)/config.json:/data/config.json \
    -e CONFIG_PATH=/data/config.json \
    ... \ # other config
    ghcr.io/sourcebot-dev/sourcebot:latest
```

Sourcebot performs syncing in the background. Syncing consists of two steps:
1. Fetch the latest changes from `HEAD` (and any [additional branches](/docs/features/search/multi-branch-indexing)) from the code host.
2. Re-indexes the repository.

This is processed in a [job queue](/docs/overview#architecture), and is parallelized across multiple worker processes. Jobs will take longer to complete the first time a repository is synced, or when a diff is large.

On the home page, you can view the sync status of ongoing jobs:

<video
    autoPlay
    muted
    loop
    playsInline
    className="w-full aspect-video"
    src="https://framerusercontent.com/assets/7YyxK8ctPEy9Rf68X2kIdMI.mp4"
></video>

## Getting started
---

To get started, pick a platform below and follow the instructions to connect your code.

<SupportedPlatforms />

<Note>Missing your code host? [Submit a feature request on GitHub](https://github.com/sourcebot-dev/sourcebot/discussions/categories/ideas).</Note>


## Schema reference
---

<Accordion title="Reference">
[schemas/v3/index.json](https://github.com/sourcebot-dev/sourcebot/blob/main/schemas/v3/index.json)

<ConfigSchema />

</Accordion>