Skip to content

docs(github-app): add github app connection auth docs #735

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
msukkari merged 3 commits into from
Jan 14, 2026
Merged

docs(github-app): add github app connection auth docs #735

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8c05bd5
add github app connection auth docs
msukkari Jan 14, 2026
fd67280
changelog
msukkari Jan 14, 2026
504f786
no defaultOpen
msukkari Jan 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Changed
- Remove references to demo from docs. [#734](https://github.com/sourcebot-dev/sourcebot/pull/734)
- Add docs for GitHub App connection auth. #[735](https://github.com/sourcebot-dev/sourcebot/pull/735)

### Fixed
- Fixed issue where 403 errors were being raised during a user driven permission sync against a self-hosted code host. [#729](https://github.com/sourcebot-dev/sourcebot/pull/729)
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/configuration/idp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ Sourcebot uses [Auth.js](https://authjs.dev/) to connect to external identity pr

[Auth.js GitHub Provider Docs](https://authjs.dev/getting-started/providers/github)

A GitHub connection can be used for either [authentication](/docs/configuration/auth) or [permission syncing](/docs/features/permission-syncing). This is controlled using the `purpose` field
A GitHub connection can be used for [authentication](/docs/configuration/auth) and/or [permission syncing](/docs/features/permission-syncing). This is controlled using the `purpose` field
in the GitHub identity provider config.

<Accordion title="instructions">
Expand Down Expand Up @@ -115,7 +115,7 @@ in the GitHub identity provider config.

[Auth.js GitLab Provider Docs](https://authjs.dev/getting-started/providers/gitlab)

A GitLab connection can be used for either [authentication](/docs/configuration/auth) or [permission syncing](/docs/features/permission-syncing). This is controlled using the `purpose` field
A GitLab connection can be used for [authentication](/docs/configuration/auth) and/or [permission syncing](/docs/features/permission-syncing). This is controlled using the `purpose` field
in the GitLab identity provider config.

<Accordion title="instructions">
Expand Down
143 changes: 101 additions & 42 deletions docs/docs/connections/github.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ icon: GitHub
---

import GitHubSchema from '/snippets/schemas/v3/github.schema.mdx'
import LicenseKeyRequired from '/snippets/license-key-required.mdx'

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

Expand Down Expand Up @@ -106,56 +107,114 @@ If you're not familiar with Sourcebot [connections](/docs/connections/overview),

## 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:
In order to index private repositories, you'll need to authenticate with GitHub. Sourcebot supports the following mechanisms of authenticating a GitHub connection:


<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 title="GitHub App">
<LicenseKeyRequired />
<Steps>
<Step title="Register a new GitHub App">
Register a new [GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app#registering-a-github-app) and provide it with the following permissions:
- “Contents” repository permissions (read)
- “Metadata” repository permissions (read)
- “Members” organization permissions (read)
- “Email addresses” account permissions (read)

This can be the same GitHub App you've registered and configured as an [external identity provider](/docs/configuration/idp#github)
</Step>
<Step title="Install the GitHub App">
Install the GitHub App into the GitHub orgs that you want Sourcebot to be aware of. **Sourcebot will only be able to index repos from orgs with the GitHub App installed.**
</Step>
<Step title="Create a private key for the GitHub App">
Create a [private key](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps) for the GitHub App.
</Step>
<Step title="Define the GitHub App config in Sourcebot">
Create a new `apps` object in the Sourcebot [config file](/docs/configuration/config-file). The private key you created in the previous
step must be passed in as a [token](/docs/configuration/config-file#tokens).
```json wrap icon="code"
"apps": [
{
"type": "github", // must be github
"id": "1234567", // Your GitHub App ID
"privateKey": {
"env": "GITHUB_APP_PRIVATE_KEY" // Token which contains your Github App private key
}
}
]
```
</Step>
<Step title="You're done!">
That's it! Sourcebot will now use this GitHub App to authenticate when pulling repos for this connection.
</Step>
</Steps>
</Accordion>
<Accordion title="Fine-grained personal access tokens">
<Steps>
<Step title="Create PAT">
Create a new fine-grained PAT [here](https://github.com/settings/personal-access-tokens/new). 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)
</Step>
<Step title="Pass PAT into Sourcebot">
Next, provide the PAT via a [token](/docs/configuration/config-file#tokens) which is referenced in the `token` field in the [connection](/docs/connections/overview) config object.

The most common mechanism of doing this is defining an environment variable that holds the PAT:

```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 ..
}
```
</Step>
<Step title="You're done!">
That's it! Sourcebot will now use this PAT to authenticate when pulling repos for this connection.
</Step>
</Steps>
</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)
<Steps>
<Step title="Create PAT">
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)
</Step>
<Step title="Pass PAT into Sourcebot">
Next, provide the PAT via a [token](/docs/configuration/config-file#tokens) which is referenced in the `token` field in the [connection](/docs/connections/overview) config object.

The most common mechanism of doing this is defining an environment variable that holds the PAT:

```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 ..
}
```
</Step>
<Step title="You're done!">
That's it! Sourcebot will now use this PAT to authenticate when pulling repos for this connection.
</Step>
</Steps>
</Accordion>
</AccordionGroup>

Next, provide the access token via an environment variable [token](/docs/configuration/config-file#tokens) which is referenced in the `token` property:

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

## Connecting to a custom GitHub host

To connect to a GitHub host other than `github.com`, provide the `url` property to your config:
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/connections/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Each connection defines how Sourcebot should authenticate and interact with a pa
"env": "GITHUB_TOKEN"
}
},
// 2. A self-hosted GitLab instance
// 2. A connection to a self-hosted GitLab instance
"gitlab-connection": {
"type": "gitlab",
"url": "https://gitlab.example.com",
Expand Down