sourcebot-dev · brendan-kellam · May 28, 2025 · May 18, 2025 · May 18, 2025 · May 19, 2025
diff --git a/.env.development b/.env.development
@@ -18,10 +18,10 @@ SRC_TENANT_ENFORCEMENT_MODE=strict
 AUTH_SECRET="00000000000000000000000000000000000000000000"
 AUTH_URL="http://localhost:3000"
 # AUTH_CREDENTIALS_LOGIN_ENABLED=true
-# AUTH_GITHUB_CLIENT_ID=""
-# AUTH_GITHUB_CLIENT_SECRET=""
-# AUTH_GOOGLE_CLIENT_ID=""
-# AUTH_GOOGLE_CLIENT_SECRET=""
+# AUTH_EE_GITHUB_CLIENT_ID=""
+# AUTH_EE_GITHUB_CLIENT_SECRET=""
+# AUTH_EE_GOOGLE_CLIENT_ID=""
+# AUTH_EE_GOOGLE_CLIENT_SECRET=""
 
 DATA_CACHE_DIR=${PWD}/.sourcebot  # Path to the sourcebot cache dir (ex. ~/sourcebot/.sourcebot)
 # CONFIG_PATH=${PWD}/config.json # Path to the sourcebot config file (if one exists)

diff --git a/docs/docs.json b/docs/docs.json
@@ -63,6 +63,7 @@
                     {
                         "group": "More",
                         "pages": [
+                            "docs/more/api-keys",
                             "docs/more/roles-and-permissions",
                             "docs/more/mcp-server"
                         ]
@@ -77,17 +78,16 @@
                         "group": "Getting Started",
                         "pages": [
                             "self-hosting/overview",
-                            "self-hosting/configuration",
                             "self-hosting/license-key"
                         ]
                     },
                     {
-                        "group": "More",
+                        "group": "Configuration",
                         "pages": [
-                            "self-hosting/more/authentication",
-                            "self-hosting/more/tenancy",
-                            "self-hosting/more/transactional-emails",
-                            "self-hosting/more/declarative-config"
+                            "self-hosting/configuration/environment-variables",
+                            "self-hosting/configuration/authentication",
+                            "self-hosting/configuration/transactional-emails",
+                            "self-hosting/configuration/declarative-config"
                         ]
                     },
                     {
@@ -98,7 +98,8 @@
                     {
                         "group": "Upgrade",
                         "pages": [
-                            "self-hosting/upgrade/v2-to-v3-guide"
+                            "self-hosting/upgrade/v2-to-v3-guide",
+                            "self-hosting/upgrade/v3-to-v4-guide"
                         ]
                     }
                 ]

diff --git a/docs/docs/agents/review-agent.mdx b/docs/docs/agents/review-agent.mdx
@@ -53,6 +53,7 @@ Before you get started, make sure you have an OpenAPI account that you can creat
         directory that you mount to Sourcebot
         ![GitHub App Private Key](/images/github_app_private_key.png)
         - `OPENAI_API_KEY`: Your OpenAI API key
+        - `REVIEW_AGENT_API_KEY`: The Sourcebot API key that the review agent uses to hit the Sourcebot API to fetch code context
         - `REVIEW_AGENT_AUTO_REVIEW_ENABLED` (default: `false`): If enabled, the review agent will automatically review any new or updated PR. If disabled, you must invoke it using the command defined by `REVIEW_AGENT_REVIEW_COMMAND`
         - `REVIEW_AGENT_REVIEW_COMMAND` (default: `review`): The command that invokes the review agent (ex. `/review`) when a user comments on the PR. Don't include the slash character in this value.
 
@@ -76,6 +77,7 @@ Before you get started, make sure you have an OpenAPI account that you can creat
                     GITHUB_APP_ID: "my-github-app-id"
                     GITHUB_APP_WEBHOOK_SECRET: "my-github-app-webhook-secret"
                     GITHUB_APP_PRIVATE_KEY_PATH: "/data/review-agent-key.pem"
+                    REVIEW_AGENT_API_KEY: "sourcebot-my-key"
                     OPENAI_API_KEY: "sk-proj-my-open-api-key"
         ```
     </Step>

diff --git a/docs/docs/more/api-keys.mdx b/docs/docs/more/api-keys.mdx
@@ -0,0 +1,8 @@
+---
+title: API Keys
+---
+
+An API Key is required when querying Sourcebot outside the context of the web app client (ex. MCP server, review agent). To create an API key, login to your Sourcebot instance and navigate to
+**Settings -> API Keys**:
+
+![API Keys UI](/images/api_key.png)
diff --git a/docs/docs/more/mcp-server.mdx b/docs/docs/more/mcp-server.mdx
@@ -176,6 +176,7 @@ Parameters:
 | Name                     | Default                | Description                                       |
 |:-------------------------|:-----------------------|:--------------------------------------------------|
 | `SOURCEBOT_HOST`         | http://localhost:3000  | URL of your Sourcebot instance.                   |
+| `SOURCEBOT_API_KEY`      | -                      | Sourcebot API key.                                |
 | `DEFAULT_MINIMUM_TOKENS` | 10000                  | Minimum number of tokens to return in responses.  |
 | `DEFAULT_MATCHES`        | 10000                  | Number of code matches to fetch per search.       |
 | `DEFAULT_CONTEXT_LINES`  | 5                      | Lines of context to include above/below matches.  |
diff --git a/docs/docs/more/roles-and-permissions.mdx b/docs/docs/more/roles-and-permissions.mdx
@@ -4,8 +4,7 @@ title: Roles and Permissions
 
 <Note>Looking to sync permissions with your identify provider? We're working on it - [reach out](https://www.sourcebot.dev/contact) to us to learn more</Note>
 
-If you're using Sourcebot Cloud, or are self-hosting with [authentication](/self-hosting/more/authentication) enabled, you may have multiple members in your organization. Each
-member has a role which defines their permissions:
+Each member has a role which defines their permissions within an organization:
 
 | Role | Permission |
 | :--- | :--------- |

diff --git a/docs/images/api_key.png b/docs/images/api_key.png
diff --git a/docs/images/join_request_email.png b/docs/images/join_request_email.png
diff --git a/docs/images/login.png b/docs/images/login.png
diff --git a/docs/images/login_basic.png b/docs/images/login_basic.png
diff --git a/docs/images/pending_approval.png b/docs/images/pending_approval.png
diff --git a/docs/self-hosting/configuration.mdx b/docs/self-hosting/configuration.mdx
diff --git a/docs/self-hosting/configuration/authentication.mdx b/docs/self-hosting/configuration/authentication.mdx
@@ -0,0 +1,109 @@
+---
+title: Authentication
+sidebarTitle: Authentication
+---
+
+<Warning>Make sure the `AUTH_URL` environment variable is [configured correctly](/self-hosting/configuration) when using Sourcebot behind a domain.</Warning>
+
+Sourcebot has built-in authentication that gates access to your organization. OAuth, email codes, and email / password are supported. 
+
+The first account that's registered on a Sourcebot deployment is made the owner. All other users who register must be [approved](/self-hosting/configuration/authentication#approving-new-members) by the owner.
+
+![Login Page](/images/login.png)
+
+
+# Approving New Members
+
+All account registrations after the first account must be approved by the owner. The owner can see all join requests by going into **Settings -> Members**.
+
+If you have an [enterprise license](/self-hosting/license-key), you can enable [AUTH_EE_ENABLE_JIT_PROVISIONING](/self-hosting/configuration/authentication#enterprise-authentication-providers) to 
+have Sourcebot accounts automatically created and approved on registration.
+
+You can setup emails to be sent when new join requests are created/approved by configurating [transactional emails](/self-hosting/configuration/transactional-emails)
+# Authentication Providers
+
+To enable an authentication provider in Sourcebot, configure the required environment variables for the provider. Under the hood, Sourcebot uses Auth.js which supports [many providers](https://authjs.dev/getting-started/authentication/oauth). Submit a [feature request on GitHub](https://github.com/sourcebot-dev/sourcebot/discussions/categories/ideas) if you want us to add support for a specific provider.
+
+## Core Authentication Providers
+
+### Email / Password
+---
+Email / password authentication is enabled by default. It can be **disabled** by setting `AUTH_CREDENTIALS_LOGIN_ENABLED` to `false`.
+
+### Email codes
+---
+Email codes are 6 digit codes sent to a provided email. Email codes are enabled when transactional emails are configured using the following environment variables:
+
+- `AUTH_EMAIL_CODE_LOGIN_ENABLED`
+- `SMTP_CONNECTION_URL`
+- `EMAIL_FROM_ADDRESS`
+
+
+See [transactional emails](/self-hosting/configuration/transactional-emails) for more details.
+
+## Enterprise Authentication Providers
+
+The following authentication providers require an [enterprise license](/self-hosting/license-key) to be enabled.
+
+By default, a new user registering using these providers must have their join request accepted by the owner of the organization to join. To allow a user to join automatically when
+they register for the first time, set the `AUTH_EE_ENABLE_JIT_PROVISIONING` environment variable to `true`. 
+
+### GitHub
+---
+
+[Auth.js GitHub Provider Docs](https://authjs.dev/getting-started/providers/github)
+
+**Required environment variables:**
+- `AUTH_EE_GITHUB_CLIENT_ID`
+- `AUTH_EE_GITHUB_CLIENT_SECRET`
+
+Optional environment variables:
+- `AUTH_EE_GITHUB_BASE_URL` - Base URL for GitHub Enterprise (defaults to https://github.com)
+
+### GitLab
+---
+
+[Auth.js GitLab Provider Docs](https://authjs.dev/getting-started/providers/gitlab)
+
+**Required environment variables:**
+- `AUTH_EE_GITLAB_CLIENT_ID`
+- `AUTH_EE_GITLAB_CLIENT_SECRET`
+
+Optional environment variables:
+- `AUTH_EE_GITLAB_BASE_URL` - Base URL for GitLab instance (defaults to https://gitlab.com)
+
+### Google
+---
+
+[Auth.js Google Provider Docs](https://authjs.dev/getting-started/providers/google)
+
+**Required environment variables:**
+- `AUTH_EE_GOOGLE_CLIENT_ID`
+- `AUTH_EE_GOOGLE_CLIENT_SECRET`
+
+### Okta
+---
+
+[Auth.js Okta Provider Docs](https://authjs.dev/getting-started/providers/okta)
+
+**Required environment variables:**
+- `AUTH_EE_OKTA_CLIENT_ID`
+- `AUTH_EE_OKTA_CLIENT_SECRET`
+- `AUTH_EE_OKTA_ISSUER`
+
+### Keycloak
+---
+
+[Auth.js Keycloak Provider Docs](https://authjs.dev/getting-started/providers/keycloak)
+
+**Required environment variables:**
+- `AUTH_EE_KEYCLOAK_CLIENT_ID`
+- `AUTH_EE_KEYCLOAK_CLIENT_SECRET`
+- `AUTH_EE_KEYCLOAK_ISSUER`
+
+---
+
+# Troubleshooting
+
+- If you experience issues logging in, logging out, or accessing an organization you should have access to, try clearing your cookies & performing a full page refresh (`Cmd/Ctrl + Shift + R` on most browsers).
+- Still not working? Reach out to us on our [discord](https://discord.com/invite/6Fhp27x7Pb) or [github discussions](https://github.com/sourcebot-dev/sourcebot/discussions)
diff --git a/.../self-hosting/more/declarative-config.mdx → ...ting/configuration/declarative-config.mdx b/.../self-hosting/more/declarative-config.mdx → ...ting/configuration/declarative-config.mdx
@@ -5,10 +5,6 @@ sidebarTitle: Declarative config
 
 import ConfigSchema from '/snippets/schemas/v3/index.schema.mdx'
 
-<Warning>
-Declaratively defining `connections` is not available when [multi-tenancy](/self-hosting/more/tenancy) is enabled.
-</Warning>
-
 Some teams require Sourcebot to be configured via a file (where it can be stored in version control, run through CI/CD pipelines, etc.) instead of a web UI. For more information on configuring connections, see this [overview](/docs/connections/overview).