Overview

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:

// 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.

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:

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) from the code host.
2. Re-indexes the repository.

This is processed in a job queue, 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:

​

Getting started

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

​

Schema reference