From 3b4259f32cdf14d52ebc612b24300bfd966f2469 Mon Sep 17 00:00:00 2001 From: bkellam Date: Mon, 3 Nov 2025 19:50:26 -0800 Subject: [PATCH] docs --- docs/docs/configuration/config-file.mdx | 103 ++++++++++++++++ .../configuration/environment-variables.mdx | 4 +- docs/docs/connections/ado-cloud.mdx | 2 +- docs/docs/connections/ado-server.mdx | 2 +- docs/docs/connections/bitbucket-cloud.mdx | 2 +- .../connections/bitbucket-data-center.mdx | 2 +- docs/docs/connections/gitea.mdx | 2 +- docs/docs/connections/github.mdx | 2 +- docs/docs/connections/gitlab.mdx | 2 +- .../v3/environmentOverrides.schema.mdx | 115 ++++++++++++++++++ docs/snippets/schemas/v3/index.schema.mdx | 112 +---------------- .../src/v3/environmentOverrides.schema.ts | 114 +++++++++++++++++ .../src/v3/environmentOverrides.type.ts | 40 ++++++ packages/schemas/src/v3/index.schema.ts | 112 +---------------- packages/schemas/src/v3/index.type.ts | 3 - schemas/v3/environmentOverrides.json | 85 +++++++++++++ schemas/v3/index.json | 86 +------------ 17 files changed, 470 insertions(+), 318 deletions(-) create mode 100644 docs/snippets/schemas/v3/environmentOverrides.schema.mdx create mode 100644 packages/schemas/src/v3/environmentOverrides.schema.ts create mode 100644 packages/schemas/src/v3/environmentOverrides.type.ts create mode 100644 schemas/v3/environmentOverrides.json diff --git a/docs/docs/configuration/config-file.mdx b/docs/docs/configuration/config-file.mdx index 58d7a1b1..9985e457 100644 --- a/docs/docs/configuration/config-file.mdx +++ b/docs/docs/configuration/config-file.mdx @@ -3,6 +3,9 @@ title: Config File sidebarTitle: Config file --- +import ConfigSchema from '/snippets/schemas/v3/index.schema.mdx' +import EnvironmentOverridesSchema from '/snippets/schemas/v3/environmentOverrides.schema.mdx' + When self-hosting Sourcebot, you **must** provide it a config file. This is done by defining a config file in a volume that's mounted to Sourcebot, and providing the path to this file in the `CONFIG_PATH` environment variable. For example: @@ -49,3 +52,103 @@ The following are settings that can be provided in your config file to modify So | `enablePublicAccess` **(deprecated)** | boolean | false | — | Use the `FORCE_ENABLE_ANONYMOUS_ACCESS` environment variable instead. | | `experiment_repoDrivenPermissionSyncIntervalMs` | number | 24 hours | 1 | Interval at which the repo permission syncer should run. | | `experiment_userDrivenPermissionSyncIntervalMs` | number | 24 hours | 1 | Interval at which the user permission syncer should run. | + +# Tokens + +Tokens are used to securely pass secrets to Sourcebot in a config file. They are used in various places, including connections, language model providers, auth providers, etc. Tokens can be passed as either environment variables or Google Cloud secrets: + + + + ```json + { + "token": { + "env": "TOKEN_NAME" + } + } + ``` + + + ```json + { + "token": { + "googleCloudSecret": "projects//secrets//versions/" + } + } + ``` + + + +# Overriding environment variables from the config + +You can override / set environment variables from the config file by using the `environmentOverrides` property. Overrides can be of type `string`, `number`, `boolean`, or a [token](/docs/configuration/config-file#tokens). Tokens are useful when you want to configure a environment variable using a Google Cloud Secret or other supported secret management service. + + + + ```jsonc + { + "environmentOverrides": { + "DATABASE_URL": { + "type": "token", + "value": { + "googleCloudSecret": "projects//secrets/postgres-connection-string/versions/latest" + } + }, + "REDIS_URL": { + "type": "token", + "value": { + "googleCloudSecret": "projects//secrets/redis-connection-string/versions/latest" + } + } + }, + } + ``` + + + + ```jsonc + { + "environmentOverrides": { + "EMAIL_FROM_ADDRESS": { + "type": "string", + "value": "hello@sourcebot.dev" + } + } + } + ``` + + + + ```jsonc + { + "environmentOverrides": { + "SOURCEBOT_CHAT_MODEL_TEMPERATURE": { + "type": "number", + "value": 0.5 + } + } + } + ``` + + + + ```jsonc + { + "environmentOverrides": { + "SOURCEBOT_TELEMETRY_DISABLED": { + "type": "boolean", + "value": false + } + } + } + ``` + + + + +**Note:** Overrides are **not** set as system environment variables, and instead are resolved at runtime on startup and stored in memory. + + +[schemas/v3/environmentOverrides.json](https://github.com/sourcebot-dev/sourcebot/blob/main/schemas/v3/environmentOverrides.json) + + + \ No newline at end of file diff --git a/docs/docs/configuration/environment-variables.mdx b/docs/docs/configuration/environment-variables.mdx index b6fba9eb..1fc78e2f 100644 --- a/docs/docs/configuration/environment-variables.mdx +++ b/docs/docs/configuration/environment-variables.mdx @@ -1,7 +1,6 @@ --- title: Environment variables sidebarTitle: Environment variables -mode: "wide" --- This page provides a detailed reference of all environment variables supported by Sourcebot. If you're just looking to get up and running, we recommend starting with the [deployment guide](/docs/deployment-guide) instead. @@ -71,3 +70,6 @@ The following environment variables allow you to configure your Sourcebot deploy | `REVIEW_AGENT_LOGGING_ENABLED` | `true` |

Enables/disables logging for the review agent. Logs are saved in `DATA_CACHE_DIR/review-agent`

| | `REVIEW_AGENT_REVIEW_COMMAND` | `review` |

The command used to trigger a code review by the review agent.

| +### Overriding environment variables from the config + +You can override environment variables from the config file by using the `environmentOverrides` property. See [this doc](/docs/configuration/config-file#overriding-environment-variables-from-the-config) for more info. \ No newline at end of file diff --git a/docs/docs/connections/ado-cloud.mdx b/docs/docs/connections/ado-cloud.mdx index 7071afb1..92bde048 100644 --- a/docs/docs/connections/ado-cloud.mdx +++ b/docs/docs/connections/ado-cloud.mdx @@ -86,7 +86,7 @@ If you're not familiar with Sourcebot [connections](/docs/connections/overview), Azure Devops Cloud requires you to provide a PAT in order to index your repositories. To learn how to create PAT, check out the [Azure Devops docs](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=Windows). Sourcebot needs the `Read` access for the `Code` scope in order to find and clone your repos. -Next, provide the access token via an environment variable which is referenced in the `token` property: +Next, provide the access [token](/docs/configuration/config-file#tokens) via an environment variable which is referenced in the `token` property: diff --git a/docs/docs/connections/ado-server.mdx b/docs/docs/connections/ado-server.mdx index a62d94c2..9687f827 100644 --- a/docs/docs/connections/ado-server.mdx +++ b/docs/docs/connections/ado-server.mdx @@ -100,7 +100,7 @@ If you're not familiar with Sourcebot [connections](/docs/connections/overview), Azure Devops Server requires you to provide a PAT in order to index your repositories. To learn how to create PAT, check out the [Azure Devops docs](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=Windows). Sourcebot needs the `Read` access for the `Code` scope in order to find and clone your repos. -Next, provide the access token via an environment variable which is referenced in the `token` property: +Next, provide the access [token](/docs/configuration/config-file#tokens) via an environment variable which is referenced in the `token` property: diff --git a/docs/docs/connections/bitbucket-cloud.mdx b/docs/docs/connections/bitbucket-cloud.mdx index bde7a665..56b140f8 100644 --- a/docs/docs/connections/bitbucket-cloud.mdx +++ b/docs/docs/connections/bitbucket-cloud.mdx @@ -78,7 +78,7 @@ If you're not familiar with Sourcebot [connections](/docs/connections/overview), ## Authenticating with Bitbucket Cloud -In order to index private repositories, you'll need to provide authentication credentials. You can do this using an `App Password` or an `Access Token` +In order to index private repositories, you'll need to provide authentication credentials via a [token](/docs/configuration/config-file#tokens). You can do this using an `App Password` or an `Access Token` diff --git a/docs/docs/connections/bitbucket-data-center.mdx b/docs/docs/connections/bitbucket-data-center.mdx index 77479e46..bfda0934 100644 --- a/docs/docs/connections/bitbucket-data-center.mdx +++ b/docs/docs/connections/bitbucket-data-center.mdx @@ -70,7 +70,7 @@ If you're not familiar with Sourcebot [connections](/docs/connections/overview), ## Authenticating with Bitbucket Data Center -In order to index private repositories, you'll need to provide an access token to Sourcebot. +In order to index private repositories, you'll need to provide an access token to Sourcebot via a [token](/docs/configuration/config-file#tokens). Create an access token for the desired scope (repo, project, or workspace). Visit the official [Bitbucket Data Center docs](https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html) for more info. diff --git a/docs/docs/connections/gitea.mdx b/docs/docs/connections/gitea.mdx index 0f8505cb..0b4efe15 100644 --- a/docs/docs/connections/gitea.mdx +++ b/docs/docs/connections/gitea.mdx @@ -81,7 +81,7 @@ In order to index private repositories, you'll need to generate a Gitea access t ![Gitea Access token creation](/images/gitea_pat_creation.png) -Next, provide the access token via an environment variable which is referenced in the `token` property: +Next, provide the access token via an environment variable [token](/docs/configuration/config-file#tokens) which is referenced in the `token` property: diff --git a/docs/docs/connections/github.mdx b/docs/docs/connections/github.mdx index e87a1f6d..4d3384b4 100644 --- a/docs/docs/connections/github.mdx +++ b/docs/docs/connections/github.mdx @@ -128,7 +128,7 @@ In order to index private repositories, you'll need to generate a access token a -Next, provide the access token via an environment variable which is referenced in the `token` property: +Next, provide the access token via an environment variable [token](/docs/configuration/config-file#tokens) which is referenced in the `token` property: diff --git a/docs/docs/connections/gitlab.mdx b/docs/docs/connections/gitlab.mdx index 1b71b7ae..25603537 100644 --- a/docs/docs/connections/gitlab.mdx +++ b/docs/docs/connections/gitlab.mdx @@ -116,7 +116,7 @@ In order to index private projects, you'll need to generate a GitLab Personal Ac ![GitLab PAT Scope](/images/gitlab_pat_scopes.png) -Next, provide the PAT via an environment variable which is referenced in the `token` property: +Next, provide the PAT via an environment variable [token](/docs/configuration/config-file#tokens) which is referenced in the `token` property: diff --git a/docs/snippets/schemas/v3/environmentOverrides.schema.mdx b/docs/snippets/schemas/v3/environmentOverrides.schema.mdx new file mode 100644 index 00000000..b6a82574 --- /dev/null +++ b/docs/snippets/schemas/v3/environmentOverrides.schema.mdx @@ -0,0 +1,115 @@ +{/* THIS IS A AUTO-GENERATED FILE. DO NOT MODIFY MANUALLY! */} +```json +{ + "type": "object", + "description": "Environment variable overrides.", + "name": "EnvironmentOverrides", + "not": { + "$comment": "List of environment variables that are not allowed to be overridden.", + "anyOf": [ + { + "required": [ + "CONFIG_PATH" + ] + } + ] + }, + "patternProperties": { + "^[a-zA-Z0-9_-]+$": { + "oneOf": [ + { + "type": "object", + "properties": { + "type": { + "const": "token" + }, + "value": { + "anyOf": [ + { + "type": "object", + "properties": { + "env": { + "type": "string", + "description": "The name of the environment variable that contains the token." + } + }, + "required": [ + "env" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "googleCloudSecret": { + "type": "string", + "description": "The resource name of a Google Cloud secret. Must be in the format `projects//secrets//versions/`. See https://cloud.google.com/secret-manager/docs/creating-and-accessing-secrets" + } + }, + "required": [ + "googleCloudSecret" + ], + "additionalProperties": false + } + ] + } + }, + "required": [ + "type", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "const": "string" + }, + "value": { + "type": "string" + } + }, + "required": [ + "type", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "const": "number" + }, + "value": { + "type": "number" + } + }, + "required": [ + "type", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "const": "boolean" + }, + "value": { + "type": "boolean" + } + }, + "required": [ + "type", + "value" + ], + "additionalProperties": false + } + ] + } + } +} +``` diff --git a/docs/snippets/schemas/v3/index.schema.mdx b/docs/snippets/schemas/v3/index.schema.mdx index 5b4121e4..a866a9aa 100644 --- a/docs/snippets/schemas/v3/index.schema.mdx +++ b/docs/snippets/schemas/v3/index.schema.mdx @@ -135,117 +135,6 @@ } }, "additionalProperties": false - }, - "EnvironmentOverrides": { - "type": "object", - "description": "Environment variable overrides.", - "not": { - "$comment": "List of environment variables that are not allowed to be overridden.", - "anyOf": [ - { - "required": [ - "CONFIG_PATH" - ] - } - ] - }, - "patternProperties": { - "^[a-zA-Z0-9_-]+$": { - "oneOf": [ - { - "type": "object", - "properties": { - "type": { - "const": "token" - }, - "value": { - "anyOf": [ - { - "type": "object", - "properties": { - "env": { - "type": "string", - "description": "The name of the environment variable that contains the token." - } - }, - "required": [ - "env" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "googleCloudSecret": { - "type": "string", - "description": "The resource name of a Google Cloud secret. Must be in the format `projects//secrets//versions/`. See https://cloud.google.com/secret-manager/docs/creating-and-accessing-secrets" - } - }, - "required": [ - "googleCloudSecret" - ], - "additionalProperties": false - } - ] - } - }, - "required": [ - "type", - "value" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "type": { - "const": "string" - }, - "value": { - "type": "string" - } - }, - "required": [ - "type", - "value" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "type": { - "const": "number" - }, - "value": { - "type": "number" - } - }, - "required": [ - "type", - "value" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "type": { - "const": "boolean" - }, - "value": { - "type": "boolean" - } - }, - "required": [ - "type", - "value" - ], - "additionalProperties": false - } - ] - } - } } }, "properties": { @@ -393,6 +282,7 @@ "environmentOverrides": { "type": "object", "description": "Environment variable overrides.", + "name": "EnvironmentOverrides", "not": { "$comment": "List of environment variables that are not allowed to be overridden.", "anyOf": [ diff --git a/packages/schemas/src/v3/environmentOverrides.schema.ts b/packages/schemas/src/v3/environmentOverrides.schema.ts new file mode 100644 index 00000000..a0d663c2 --- /dev/null +++ b/packages/schemas/src/v3/environmentOverrides.schema.ts @@ -0,0 +1,114 @@ +// THIS IS A AUTO-GENERATED FILE. DO NOT MODIFY MANUALLY! +const schema = { + "type": "object", + "description": "Environment variable overrides.", + "name": "EnvironmentOverrides", + "not": { + "$comment": "List of environment variables that are not allowed to be overridden.", + "anyOf": [ + { + "required": [ + "CONFIG_PATH" + ] + } + ] + }, + "patternProperties": { + "^[a-zA-Z0-9_-]+$": { + "oneOf": [ + { + "type": "object", + "properties": { + "type": { + "const": "token" + }, + "value": { + "anyOf": [ + { + "type": "object", + "properties": { + "env": { + "type": "string", + "description": "The name of the environment variable that contains the token." + } + }, + "required": [ + "env" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "googleCloudSecret": { + "type": "string", + "description": "The resource name of a Google Cloud secret. Must be in the format `projects//secrets//versions/`. See https://cloud.google.com/secret-manager/docs/creating-and-accessing-secrets" + } + }, + "required": [ + "googleCloudSecret" + ], + "additionalProperties": false + } + ] + } + }, + "required": [ + "type", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "const": "string" + }, + "value": { + "type": "string" + } + }, + "required": [ + "type", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "const": "number" + }, + "value": { + "type": "number" + } + }, + "required": [ + "type", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "const": "boolean" + }, + "value": { + "type": "boolean" + } + }, + "required": [ + "type", + "value" + ], + "additionalProperties": false + } + ] + } + } +} as const; +export { schema as environmentOverridesSchema }; \ No newline at end of file diff --git a/packages/schemas/src/v3/environmentOverrides.type.ts b/packages/schemas/src/v3/environmentOverrides.type.ts new file mode 100644 index 00000000..e9adfaec --- /dev/null +++ b/packages/schemas/src/v3/environmentOverrides.type.ts @@ -0,0 +1,40 @@ +// THIS IS A AUTO-GENERATED FILE. DO NOT MODIFY MANUALLY! + +/** + * Environment variable overrides. + */ +export interface EnvironmentOverrides { + /** + * This interface was referenced by `EnvironmentOverrides`'s JSON-Schema definition + * via the `patternProperty` "^[a-zA-Z0-9_-]+$". + */ + [k: string]: + | { + type: "token"; + value: + | { + /** + * The name of the environment variable that contains the token. + */ + env: string; + } + | { + /** + * The resource name of a Google Cloud secret. Must be in the format `projects//secrets//versions/`. See https://cloud.google.com/secret-manager/docs/creating-and-accessing-secrets + */ + googleCloudSecret: string; + }; + } + | { + type: "string"; + value: string; + } + | { + type: "number"; + value: number; + } + | { + type: "boolean"; + value: boolean; + }; +} diff --git a/packages/schemas/src/v3/index.schema.ts b/packages/schemas/src/v3/index.schema.ts index 115df223..67951db0 100644 --- a/packages/schemas/src/v3/index.schema.ts +++ b/packages/schemas/src/v3/index.schema.ts @@ -134,117 +134,6 @@ const schema = { } }, "additionalProperties": false - }, - "EnvironmentOverrides": { - "type": "object", - "description": "Environment variable overrides.", - "not": { - "$comment": "List of environment variables that are not allowed to be overridden.", - "anyOf": [ - { - "required": [ - "CONFIG_PATH" - ] - } - ] - }, - "patternProperties": { - "^[a-zA-Z0-9_-]+$": { - "oneOf": [ - { - "type": "object", - "properties": { - "type": { - "const": "token" - }, - "value": { - "anyOf": [ - { - "type": "object", - "properties": { - "env": { - "type": "string", - "description": "The name of the environment variable that contains the token." - } - }, - "required": [ - "env" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "googleCloudSecret": { - "type": "string", - "description": "The resource name of a Google Cloud secret. Must be in the format `projects//secrets//versions/`. See https://cloud.google.com/secret-manager/docs/creating-and-accessing-secrets" - } - }, - "required": [ - "googleCloudSecret" - ], - "additionalProperties": false - } - ] - } - }, - "required": [ - "type", - "value" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "type": { - "const": "string" - }, - "value": { - "type": "string" - } - }, - "required": [ - "type", - "value" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "type": { - "const": "number" - }, - "value": { - "type": "number" - } - }, - "required": [ - "type", - "value" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "type": { - "const": "boolean" - }, - "value": { - "type": "boolean" - } - }, - "required": [ - "type", - "value" - ], - "additionalProperties": false - } - ] - } - } } }, "properties": { @@ -392,6 +281,7 @@ const schema = { "environmentOverrides": { "type": "object", "description": "Environment variable overrides.", + "name": "EnvironmentOverrides", "not": { "$comment": "List of environment variables that are not allowed to be overridden.", "anyOf": [ diff --git a/packages/schemas/src/v3/index.type.ts b/packages/schemas/src/v3/index.type.ts index 4464782c..669a9511 100644 --- a/packages/schemas/src/v3/index.type.ts +++ b/packages/schemas/src/v3/index.type.ts @@ -162,9 +162,6 @@ export interface SearchContext { } /** * Environment variable overrides. - * - * This interface was referenced by `SourcebotConfig`'s JSON-Schema - * via the `definition` "EnvironmentOverrides". */ export interface EnvironmentOverrides { /** diff --git a/schemas/v3/environmentOverrides.json b/schemas/v3/environmentOverrides.json new file mode 100644 index 00000000..a9694994 --- /dev/null +++ b/schemas/v3/environmentOverrides.json @@ -0,0 +1,85 @@ +{ + "type": "object", + "description": "Environment variable overrides.", + "name": "EnvironmentOverrides", + "not": { + "$comment": "List of environment variables that are not allowed to be overridden.", + "anyOf": [ + { + "required": [ + "CONFIG_PATH" + ] + } + ] + }, + "patternProperties": { + "^[a-zA-Z0-9_-]+$": { + "oneOf": [ + { + "type": "object", + "properties": { + "type": { + "const": "token" + }, + "value": { + "$ref": "./shared.json#/definitions/Token" + } + }, + "required": [ + "type", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "const": "string" + }, + "value": { + "type": "string" + } + }, + "required": [ + "type", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "const": "number" + }, + "value": { + "type": "number" + } + }, + "required": [ + "type", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "const": "boolean" + }, + "value": { + "type": "boolean" + } + }, + "required": [ + "type", + "value" + ], + "additionalProperties": false + } + ] + } + } +} \ No newline at end of file diff --git a/schemas/v3/index.json b/schemas/v3/index.json index 038d0169..10048a34 100644 --- a/schemas/v3/index.json +++ b/schemas/v3/index.json @@ -83,90 +83,6 @@ }, "SearchContext": { "$ref": "./searchContext.json" - }, - "EnvironmentOverrides": { - "type": "object", - "description": "Environment variable overrides.", - "not": { - "$comment": "List of environment variables that are not allowed to be overridden.", - "anyOf": [ - { - "required": [ - "CONFIG_PATH" - ] - } - ] - }, - "patternProperties": { - "^[a-zA-Z0-9_-]+$": { - "oneOf": [ - { - "type": "object", - "properties": { - "type": { - "const": "token" - }, - "value": { - "$ref": "./shared.json#/definitions/Token" - } - }, - "required": [ - "type", - "value" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "type": { - "const": "string" - }, - "value": { - "type": "string" - } - }, - "required": [ - "type", - "value" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "type": { - "const": "number" - }, - "value": { - "type": "number" - } - }, - "required": [ - "type", - "value" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "type": { - "const": "boolean" - }, - "value": { - "type": "boolean" - } - }, - "required": [ - "type", - "value" - ], - "additionalProperties": false - } - ] - } - } } }, "properties": { @@ -187,7 +103,7 @@ "additionalProperties": false }, "environmentOverrides": { - "$ref": "#/definitions/EnvironmentOverrides" + "$ref": "./environmentOverrides.json" }, "connections": { "type": "object",