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

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

A **connection** represents Sourcebot's link to a code host platform (GitHub, GitLab, etc). Connections are defined within the [config file](/docs/configuration/config-file) you provide Sourcebot.

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.

```json wrap icon="code" Example config with 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).

## Connection Syncing

When a connection is first discovered, or the `resyncConnectionIntervalMs` [setting](/docs/configuration/config-file#settings) has exceeded, the connection will be synced. This consists of:
1. Fetching the latest changes from `HEAD` (and any [additional branches](/docs/features/search/multi-branch-indexing)) from the code host.
2. Re-indexing 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>

## Platform Connection Guides

To learn more about how to create a connection for a specific code host, check out the guides below.

<SupportedPlatforms />

<Note>Missing your code host? [Submit a feature request on GitHub](https://github.com/sourcebot-dev/sourcebot/issues/new?template=feature_request.md).</Note>


## Schema reference
---

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

<ConfigSchema />

</Accordion>
