From 8c05bd5024b01bff52eec2ec44cae2aa98730a16 Mon Sep 17 00:00:00 2001 From: msukkari Date: Tue, 13 Jan 2026 20:33:54 -0800 Subject: [PATCH 1/3] add github app connection auth docs --- docs/docs/configuration/idp.mdx | 4 +- docs/docs/connections/github.mdx | 141 ++++++++++++++++++++--------- docs/docs/connections/overview.mdx | 2 +- 3 files changed, 103 insertions(+), 44 deletions(-) diff --git a/docs/docs/configuration/idp.mdx b/docs/docs/configuration/idp.mdx index 6d2475b59..2cf5fa457 100644 --- a/docs/docs/configuration/idp.mdx +++ b/docs/docs/configuration/idp.mdx @@ -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. @@ -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. diff --git a/docs/docs/connections/github.mdx b/docs/docs/connections/github.mdx index 4d3384b44..1eff28f53 100644 --- a/docs/docs/connections/github.mdx +++ b/docs/docs/connections/github.mdx @@ -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. @@ -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: + + + + + 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) + + + 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.** + + + 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. + + + 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 + } + } + ] + ``` + + + That's it! Sourcebot will now use this GitHub App to authenticate when pulling repos for this connection. + + + - 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) + + + 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) + + + 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 .. + } + ``` + + + That's it! Sourcebot will now use this PAT to authenticate when pulling repos for this connection. + + - 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) + + + 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) + + + 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 .. + } + ``` + + + That's it! Sourcebot will now use this PAT to authenticate when pulling repos for this connection. + + -Next, provide the access token via an environment variable [token](/docs/configuration/config-file#tokens) which is referenced in the `token` property: - - - - - 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= \ - /* additional args */ \ - ghcr.io/sourcebot-dev/sourcebot:latest - ``` - - - ## Connecting to a custom GitHub host To connect to a GitHub host other than `github.com`, provide the `url` property to your config: diff --git a/docs/docs/connections/overview.mdx b/docs/docs/connections/overview.mdx index cb3b14325..e244debeb 100644 --- a/docs/docs/connections/overview.mdx +++ b/docs/docs/connections/overview.mdx @@ -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", From fd6728027e5095eaa9ed951e6d4bccd21ae2064b Mon Sep 17 00:00:00 2001 From: msukkari Date: Tue, 13 Jan 2026 20:36:06 -0800 Subject: [PATCH 2/3] changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4644e7321..2b51f837a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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) From 504f78628af1a2da41f79873586a994793c79284 Mon Sep 17 00:00:00 2001 From: msukkari Date: Tue, 13 Jan 2026 20:38:36 -0800 Subject: [PATCH 3/3] no defaultOpen --- docs/docs/connections/github.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/connections/github.mdx b/docs/docs/connections/github.mdx index 1eff28f53..fcc8944d9 100644 --- a/docs/docs/connections/github.mdx +++ b/docs/docs/connections/github.mdx @@ -149,7 +149,7 @@ In order to index private repositories, you'll need to authenticate with GitHub. - + 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.