sourcebot/docs/docs/connections/github.mdx

---
title: Linking code from GitHub
sidebarTitle: GitHub
icon: GitHub
---

import GitHubSchema from '/snippets/schemas/v3/github.schema.mdx'

Sourcebot can sync code from GitHub.com, GitHub Enterprise Server, and GitHub Enterprise Cloud.

If you're not familiar with Sourcebot [connections](/docs/connections/overview), please read that overview first.

## Examples

<AccordionGroup>
    <Accordion title="Sync individual repos">
        ```json
        {
            "type": "github",
            "repos": [
                "sourcebot-dev/sourcebot",
                "getsentry/sentry",
                "torvalds/linux"
            ]
        }
        ```
    </Accordion>
    <Accordion title="Sync all repos in a organization">
        ```json
        {
            "type": "github",
            "orgs": [
                "sourcebot-dev",
                "getsentry",
                "vercel"
            ]
        }
        ```
    </Accordion>
    <Accordion title="Sync all repos owned by a user">
        ```json
        {
            "type": "github",
            "users": [
                "torvalds",
                "ggerganov"
            ]
        }
        ```
    </Accordion>
    <Accordion title="Filter repos by topic">
        ```json
        {
            "type": "github",
            // Sync all repos in `my-org` that have a topic that...
            "orgs": [
                "my-org"
            ],
            // ...match one of these glob patterns.
            "topics": [
                "test-*",
                "ci-*",
                "k8s"
            ]
        }

        ```
    </Accordion>
    <Accordion title="Exclude repos from syncing">
        ```json
        {
            "type": "github",
            // Include all repos in my-org...
            "orgs": [
                "my-org"
            ],
            // ...except:
            "exclude": {
                // repos that are archived
                "archived": true,
                // repos that are forks
                "forks": true,
                // repos that match these glob patterns
                "repos": [
                    "my-org/repo1",
                    "my-org/repo2",
                    "my-org/sub-org-1/**",
                    "my-org/sub-org-*/**"
                ],
                "size": {
                    // repos that are less than 1MB (in bytes)...
                    "min": 1048576,
                    // or repos greater than 100MB (in bytes)
                    "max": 104857600 
                },
                // repos with topics that match these glob patterns
                "topics": [
                    "test-*",
                    "ci"
                ]
            }
        }
        ```
    </Accordion>
</AccordionGroup>

## Authenticating with GitHub

In order to index private repositories, you'll need to generate a access token and provide it to Sourcebot. GitHub provides [two types](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#types-of-personal-access-tokens) of access tokens:


<AccordionGroup>
    <Accordion title="Fine-grained personal access tokens" defaultOpen>
        Create a new fine-grained PAT [here](https://github.com/settings/personal-access-tokens/new). First, select the resource owner and the repositories that you want Sourcebot to have access to.

        Next, under "Repository permissions", select permissions `Contents` and `Metadata` with access `Read-only`. The permissions should look like the following:

        ![GitHub PAT Scope](/images/github_pat_scopes_fine_grained.png)

        [GitHub docs](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#fine-grained-personal-access-tokens)
    </Accordion>
    <Accordion title="Personal access tokens (classic)">
        Create a new PAT [here](https://github.com/settings/tokens/new) and make sure you select the `repo` scope:
        
        ![GitHub PAT Scope](/images/github_pat_scopes.png)

        [GitHub docs](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#personal-access-tokens-classic)
    </Accordion>
</AccordionGroup>

Next, provide the access token via the `token` property, either as an environment variable or a secret:

<Tabs>
    <Tab title="Environment Variable">

        1. Add the `token` property to your connection config:
        ```json
        {
            "type": "github",
            "token": {
                // note: this env var can be named anything. It
                // doesn't need to be `GITHUB_TOKEN`.
                "env": "GITHUB_TOKEN"
            }
            // .. rest of config ..
        }
        ```

        2. Pass this environment variable each time you run Sourcebot:
        ```bash
        docker run \
            -e GITHUB_TOKEN=<PAT> \
            /* additional args */ \
            ghcr.io/sourcebot-dev/sourcebot:latest
        ```
    </Tab>

    <Tab title="Secret">
        <Note>Secrets are only supported when [authentication](/docs/configuration/auth/overview) is enabled.</Note>

        1. Navigate to **Secrets** in settings and create a new secret with your PAT:

        ![](/images/secrets_list.png)

        2. Add the `token` property to your connection config:

        ```json
        {
            "type": "github",
            "token": {
                "secret": "mysecret"
            }
            // .. rest of config ..
        }
        ```

    </Tab>
</Tabs>

## Connecting to a custom GitHub host

To connect to a GitHub host other than `github.com`, provide the `url` property to your config:

```json
{
    "type": "github",
    "url": "https://github.example.com"
    // .. rest of config ..
}
```

## Schema reference

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

<GitHubSchema />

</Accordion>

## See also

- [Syncing GitHub Access permissions to Sourcebot](/docs/features/permission-syncing#github)