# List connections Source: https://docs.sourcebot.dev/api-reference/connections/list-connections /api-reference/sourcebot-public.openapi.json get /api/connections Returns unique code host connections associated with at least one repository visible to the caller. Connection configuration and credentials are never included. > [!NOTE] > > This endpoint is [rate limited](/docs/api-reference/rate-limiting). Each call counts toward your daily request limit. # Get a user Source: https://docs.sourcebot.dev/api-reference/enterprise-ee/get-a-user /api-reference/sourcebot-public.openapi.json get /api/ee/user Fetches details for a single organization member by `userId`. Only organization owners can access this endpoint. # List audit records Source: https://docs.sourcebot.dev/api-reference/enterprise-ee/list-audit-records /api-reference/sourcebot-public.openapi.json get /api/ee/audit Returns a paginated list of audit log entries. Only organization owners can access this endpoint. # List users Source: https://docs.sourcebot.dev/api-reference/enterprise-ee/list-users /api-reference/sourcebot-public.openapi.json get /api/ee/users Returns all members of the organization. Only organization owners can access this endpoint. # Remove a user from the organization Source: https://docs.sourcebot.dev/api-reference/enterprise-ee/remove-a-user-from-the-organization /api-reference/sourcebot-public.openapi.json delete /api/ee/user Removes a user from the organization, revoking their access and their sessions. Only organization owners can access this endpoint. # Get a file tree Source: https://docs.sourcebot.dev/api-reference/git/get-a-file-tree /api-reference/sourcebot-public.openapi.json post /api/tree Returns the file tree for a repository at a given revision. > [!NOTE] > > This endpoint is [rate limited](/docs/api-reference/rate-limiting). Each call counts toward your daily request limit. # Get commit details Source: https://docs.sourcebot.dev/api-reference/git/get-commit-details /api-reference/sourcebot-public.openapi.json get /api/commit Returns details for a single commit, including parent commit SHAs. > [!NOTE] > > This endpoint is [rate limited](/docs/api-reference/rate-limiting). Each call counts toward your daily request limit. # Get diff between two commits Source: https://docs.sourcebot.dev/api-reference/git/get-diff-between-two-commits /api-reference/sourcebot-public.openapi.json get /api/diff Returns a structured diff between two git refs using a two-dot comparison. See [git-diff](https://git-scm.com/docs/git-diff) for details. > [!NOTE] > > This endpoint is [rate limited](/docs/api-reference/rate-limiting). Each call counts toward your daily request limit. # Get file blame Source: https://docs.sourcebot.dev/api-reference/git/get-file-blame /api-reference/sourcebot-public.openapi.json get /api/blame Returns blame information for a file at a given repository path and optional git ref. The response is split into two parts: - `ranges`: contiguous, non-overlapping line ranges, each attributed to a single commit. Ordered by `startLine`. - `commits`: commit metadata (hash, date, message, author, optional `previous` pointer for walking back through history) keyed by hash, deduplicated across ranges. Whole-file renames are followed automatically. Cross-file line moves and copies are not. > [!NOTE] > > This endpoint is [rate limited](/docs/api-reference/rate-limiting). Each call counts toward your daily request limit. # Get file contents Source: https://docs.sourcebot.dev/api-reference/git/get-file-contents /api-reference/sourcebot-public.openapi.json get /api/source Returns the raw source content of a file at a given repository path and optional git ref. > [!NOTE] > > This endpoint is [rate limited](/docs/api-reference/rate-limiting). Each call counts toward your daily request limit. # List commit authors Source: https://docs.sourcebot.dev/api-reference/git/list-commit-authors /api-reference/sourcebot-public.openapi.json get /api/commits/authors Returns a paginated list of unique authors who committed in a repository, sorted by commit count descending. Optionally scoped to a file path. > [!NOTE] > > This endpoint is [rate limited](/docs/api-reference/rate-limiting). Each call counts toward your daily request limit. # List commits Source: https://docs.sourcebot.dev/api-reference/git/list-commits /api-reference/sourcebot-public.openapi.json get /api/commits Returns a paginated list of commits for a repository. > [!NOTE] > > This endpoint is [rate limited](/docs/api-reference/rate-limiting). Each call counts toward your daily request limit. # List repositories Source: https://docs.sourcebot.dev/api-reference/repositories/list-repositories /api-reference/sourcebot-public.openapi.json get /api/repos Returns a paginated list of repositories indexed by this Sourcebot instance. > [!NOTE] > > This endpoint is [rate limited](/docs/api-reference/rate-limiting). Each call counts toward your daily request limit. # Create a scoped access token Source: https://docs.sourcebot.dev/api-reference/scoped-access-tokens/create-a-scoped-access-token /api-reference/sourcebot-public.openapi.json post /api/ee/scoped_access_token Creates an opaque bearer token that expires exactly one hour after issuance and is restricted to the requested repositories. > [!NOTE] > > The scoped access token APIs require a custom entitlement. To request access, contact [team@sourcebot.dev](mailto:team@sourcebot.dev). # Revoke a scoped access token Source: https://docs.sourcebot.dev/api-reference/scoped-access-tokens/revoke-a-scoped-access-token /api-reference/sourcebot-public.openapi.json delete /api/ee/scoped_access_token/{id} Immediately revokes a scoped access token created by the authenticated API-key owner. > [!NOTE] > > The scoped access token APIs require a custom entitlement. To request access, contact [team@sourcebot.dev](mailto:team@sourcebot.dev). # Find symbol definitions Source: https://docs.sourcebot.dev/api-reference/search-&-navigation/find-symbol-definitions /api-reference/sourcebot-public.openapi.json post /api/find_definitions Returns all locations in the codebase where the given symbol is defined. > [!NOTE] > > This endpoint is [rate limited](/docs/api-reference/rate-limiting). Each call counts toward your daily request limit. # Find symbol references Source: https://docs.sourcebot.dev/api-reference/search-&-navigation/find-symbol-references /api-reference/sourcebot-public.openapi.json post /api/find_references Returns all locations in the codebase where the given symbol is referenced. > [!NOTE] > > This endpoint is [rate limited](/docs/api-reference/rate-limiting). Each call counts toward your daily request limit. # Search code Source: https://docs.sourcebot.dev/api-reference/search-&-navigation/search-code /api-reference/sourcebot-public.openapi.json post /api/search Executes a blocking code search and returns all matching file chunks. > [!NOTE] > > This endpoint is [rate limited](/docs/api-reference/rate-limiting). Each call counts toward your daily request limit. ## Usage The `query` field supports literal, regexp, and symbol searches with filters for repository, file, language, branch, and more. See the [search syntax reference](/docs/features/search/syntax-reference) for the full query language. # Get Sourcebot version Source: https://docs.sourcebot.dev/api-reference/system/get-sourcebot-version /api-reference/sourcebot-public.openapi.json get /api/version Returns the currently running Sourcebot version string. # Health check Source: https://docs.sourcebot.dev/api-reference/system/health-check /api-reference/sourcebot-public.openapi.json get /api/health # Activating a Subscription Source: https://docs.sourcebot.dev/docs/activating-a-subscription You can activate a paid plan subscription by using either an Activation Code or a License Key. # Activation Code (Online Licensing) > [!WARNING] > > Your Sourcebot deployment must be able to send a [Service Ping](/docs/misc/service-ping) to validate your Activation Code. If your deployment is unable to send a service ping for 7 days it will enter [restricted mode](/docs/upgrade/v5-to-v6-guide#every-deployment-must-be-activated) until a successful ping is sent. The default mechanism for activating a subscription is through an Activation Code. This activation mechanism allows your Sourcebot deployment to automatically manage its subscription by regularly sychronizing with our license server. ### What data does Sourcebot collect? To enable online licensing, your Sourcebot deployment must be able to communicate with our license server through our [Service Ping](/docs/misc/service-ping). The data that is transmitted is limited to information that is required to administer your Sourcebot license and support dynamic seat increases. No sensitive data (source code, AI inputs/outputs, credentials, or user information) will ever be transmitted. For more information, please check out our [privacy policy](https://www.sourcebot.dev/privacy) # License Key (Offline Licensing) > [!NOTE] > > The default mechanism for activating a subscription is now through an [Activation Code](#activation-code-online-licensing). Offline licensing using a License Key may be requested by reaching out using our enterprise contact form on our [pricing page](https://www.sourcebot.dev/pricing) After purchasing a license key, you can activate it by setting the `SOURCEBOT_EE_LICENSE_KEY` environment variable. If you'd like to increase the number of seats on your Sourcebot deployment you must request a new license key, manually update this environment variable, and then restart your deployment. ```bash theme={null} docker run \ -e SOURCEBOT_EE_LICENSE_KEY= \ /* additional args */ \ docker.sourcebot.dev/sourcebot-dev/sourcebot:latest ``` ## FAQ #### What happens when my subscription expires? When a paid plan subscription expires, your deployment will automatically be downgraded to the Basic plan. You must upgrade your subscription in order to continue using the paid features. # Authentication Source: https://docs.sourcebot.dev/docs/api-reference/authentication To securely access and interact with Sourcebot’s API, authentication is required. Users must generate an API Key, which will be used to authenticate requests. ## Creating an API key Navigate to **Settings → API Keys** and click **Create API Key**. Copy the value - it is only shown once. ![API Keys page in Sourcebot Settings](https://mintcdn.com/sourcebot/ex_m8h1jdSrDJGnh/images/mcp_api_key_settings.png?fit=max\&auto=format\&n=ex_m8h1jdSrDJGnh\&q=85\&s=3e6196a0da5ddb0b6d1b38fe58ea5c8b) ## Using an API key Pass your API key as a Bearer token in the `Authorization` header on every request. ```bash theme={null} Authorization: Bearer ``` For example, to call the `/api/search` endpoint: ```bash theme={null} curl -X POST https://your-sourcebot-instance.com/api/search \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"query": "hello world", "matches": 10}' ``` ## Using a scoped access token > [!NOTE] > > The scoped access token APIs require a custom entitlement. To request access, contact [team@sourcebot.dev](mailto:team@sourcebot.dev). Scoped access tokens are short-lived bearer credentials intended for clients that should only access a specific set of repositories. Call `GET /api/repos` to find the integer `id` for each repository you want to include. Then create a token with a Sourcebot API key by calling `POST /api/ee/scoped_access_token` with those IDs: ```bash theme={null} curl -X POST https://your-sourcebot-instance.com/api/ee/scoped_access_token \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"repoIds": [1, 2, 3]}' ``` The response includes the scoped access token and its ID: ```json theme={null} { "id": "scoped-token-id", "token": "sbst_...", "createdAt": "2026-08-14T18:00:00.000Z", "expiresAt": "2026-08-14T19:00:00.000Z", "repoIds": [1, 2, 3] } ``` The opaque token begins with `sbst_`. It expires exactly one hour after issuance, cannot be refreshed, and is returned only once. Use it as a Bearer token with public API endpoints or the Sourcebot MCP server: ```bash theme={null} Authorization: Bearer ``` Save the `id` from the create response. Use it to revoke the token with your Sourcebot API key: ```bash theme={null} curl -X DELETE https://your-sourcebot-instance.com/api/ee/scoped_access_token/ \ -H "Authorization: Bearer " ``` Repository scope is bound internally to repository IDs and is also intersected with the creating user's current repository permissions. Creating and revoking scoped access tokens requires an API key; a scoped access token cannot mint or revoke tokens. # Rate Limiting Source: https://docs.sourcebot.dev/docs/api-reference/rate-limiting Sourcebot limits how many API requests each user can make per day. By default, each user can make up to **10,000 requests per day**. This is well above what individual use needs, including AI agents and MCP clients. If you need a higher limit, [contact us](mailto:support@sourcebot.dev). ## What counts toward the limit Only **programmatic requests** count. A request is programmatic when it's authenticated with one of the following: * An [API key](/docs/api-reference/authentication#using-an-api-key) * An OAuth token, such as the one an [MCP client](/docs/features/mcp-server) uses * A [scoped access token](/docs/api-reference/authentication#using-a-scoped-access-token) Using Sourcebot in your browser **never counts** toward the limit. This includes searching, browsing code, and chatting with Ask Sourcebot. Each request to a rate-limited endpoint counts as **one request**, including requests that fail. All of a user's API keys and tokens share the same limit. ### Rate-limited endpoints | Endpoint | Description | | - | - | | `POST /api/search` | Search code across repositories. | | `POST /api/stream_search` | Search code, streaming results as they're found. | | `POST /api/find_definitions` | Find where a symbol is defined. | | `POST /api/find_references` | Find references to a symbol. | | `GET /api/source` | Read a file's contents. | | `POST /api/files` | List all files in a repository at a given revision. | | `POST /api/tree` | List files and directories in a repository. | | `GET /api/folder_contents` | List the contents of a directory. | | `GET /api/blame` | Get blame information for a file. | | `GET /api/diff` | Get the diff between two refs. | | `GET /api/commit` | Get details for a single commit. | | `GET /api/commits` | List commits in a repository. | | `GET /api/commits/authors` | List commit authors in a repository. | | `GET /api/repos` | List repositories. | | `GET /api/connections` | List connections. | ### MCP server Each tool call to the [MCP server](/docs/features/mcp-server) counts as one request. Other MCP messages don't count, such as connecting or listing the available tools. ## Daily reset The limit resets every day at **00:00 UTC**. Unused requests don't roll over to the next day. ## Rate limit headers When a limit applies, responses from rate-limited endpoints include these headers: | Header | Description | | - | - | | `X-RateLimit-Limit` | The number of requests allowed per day. | | `X-RateLimit-Remaining` | The number of requests left today. | | `X-RateLimit-Reset` | When the limit resets, as a Unix timestamp in seconds. | ## Exceeding the limit Once a user reaches the limit, further requests to rate-limited endpoints return a `429 Too Many Requests` response until the limit resets. The `Retry-After` header gives the number of seconds until then. ```json theme={null} { "statusCode": 429, "errorCode": "API_RATE_LIMIT_EXCEEDED", "message": "API rate limit of 10000 requests per day exceeded. The limit resets at 00:00 UTC. To request a higher limit, contact support@sourcebot.dev." } ``` # Audit Logs Source: https://docs.sourcebot.dev/docs/configuration/audit-logs > [!NOTE] > > Audit Logs are only available in a paid plan. Please activate a [license key](/docs/activating-a-subscription) to use this feature. Audit logs are a collection of notable events performed by users within a Sourcebot deployment. Each audit log records information on the action taken, the user who performed the action, and when the action took place. This feature gives security and compliance teams the necessary information to ensure proper governance and administration of your Sourcebot deployment. ## Retention Policy By default, audit logs older than 180 days are automatically pruned daily. You can configure the retention period using the `SOURCEBOT_EE_AUDIT_RETENTION_DAYS` [environment variable](/docs/configuration/environment-variables). Set it to `0` to disable automatic pruning and retain logs indefinitely. ## Fetching Audit Logs Audit logs are stored in the [postgres database](/docs/misc/architecture) connected to Sourcebot. To fetch all of the audit logs, you can use the following API: ```bash icon="terminal" Fetch audit logs theme={null} curl --request GET '$SOURCEBOT_URL/api/ee/audit' \ --header 'X-Org-Domain: ~' \ --header 'X-Sourcebot-Api-Key: $SOURCEBOT_OWNER_API_KEY' ``` ```json icon="brackets-curly" wrap expandable Fetch audit logs example response theme={null} [ { "id": "cmc146k7m0003xgo2tri5t4br", "timestamp": "2025-06-17T22:48:08.914Z", "action": "api_key.created", "actorId": "cmc12tnje0000xgn58jj8655h", "actorType": "user", "actorLabel": "jane@example.com", "targetId": "205d1da1c6c3772b81d4ad697f5851fa11195176c211055ff0c1509772645d6d", "targetType": "api_key", "targetLabel": "deploy", "sourcebotVersion": "unknown", "orgId": 1 }, { "id": "cmc146c8r0001xgo2xyu0p463", "timestamp": "2025-06-17T22:47:58.587Z", "action": "user.performed_code_search", "actorId": "cmc12tnje0000xgn58jj8655h", "actorType": "user", "actorLabel": "jane@example.com", "targetId": "1", "targetType": "org", "targetLabel": null, "sourcebotVersion": "unknown", "metadata": { "source": "sourcebot-web-client" }, "orgId": 1 }, { "id": "cmc12vqgb0008xgn5nv5hl9y5", "timestamp": "2025-06-17T22:11:44.171Z", "action": "user.performed_code_search", "actorId": "cmc12tnje0000xgn58jj8655h", "actorType": "user", "actorLabel": "jane@example.com", "targetId": "1", "targetType": "org", "targetLabel": null, "sourcebotVersion": "unknown", "metadata": { "source": "sourcebot-web-client" }, "orgId": 1 }, { "id": "cmc12txwn0006xgn51ow1odid", "timestamp": "2025-06-17T22:10:20.519Z", "action": "user.performed_code_search", "actorId": "cmc12tnje0000xgn58jj8655h", "actorType": "user", "actorLabel": "jane@example.com", "targetId": "1", "targetType": "org", "targetLabel": null, "sourcebotVersion": "unknown", "metadata": { "source": "sourcebot-web-client" }, "orgId": 1 }, { "id": "cmc12tnjx0004xgn5qqeiv1ao", "timestamp": "2025-06-17T22:10:07.101Z", "action": "user.owner_created", "actorId": "cmc12tnje0000xgn58jj8655h", "actorType": "user", "actorLabel": "jane@example.com", "targetId": "1", "targetType": "org", "targetLabel": null, "sourcebotVersion": "unknown", "metadata": null, "orgId": 1 }, { "id": "cmc12tnjh0002xgn5h6vzu3rl", "timestamp": "2025-06-17T22:10:07.086Z", "action": "user.signed_in", "actorId": "cmc12tnje0000xgn58jj8655h", "actorType": "user", "actorLabel": "jane@example.com", "targetId": "cmc12tnje0000xgn58jj8655h", "targetType": "user", "targetLabel": "jane@example.com", "sourcebotVersion": "unknown", "metadata": null, "orgId": 1 } ] ``` Each record includes an `actorLabel` and a `targetLabel`. These are display names captured when the event is recorded, so a record stays readable after its actor or target is deleted. | Type | Label | | :- | :- | | `user` | The user's email | | `invite` | The invited email | | `account_join_request` | The requesting user's email | | `api_key`, `scim_token`, `oauth_client`, `mcp_server`, `connection`, `chat` | The name of the key, token, client, server, connection, or chat | | `account` | The identity provider ID (e.g., `github`) | Labels are `null` for types without a display name (e.g., `org` and `system`) and for records created before labels were added. ## Audit action types | Action | Actor Type | Target Type | | :- | :- | :- | | `account.permissions_cleared` | `system` | `account` | | `api_key.created` | `user` | `api_key` | | `api_key.creation_failed` | `user` | `org` | | `api_key.deleted` | `user` | `api_key` | | `api_key.deletion_failed` | `user` | `org` | | `audit.fetch` | `user` | `org` | | `auth.token_rejected` | `anonymous` | `org` | | `chat.deleted` | `user` | `chat` | | `chat.shared_with_users` | `user` | `chat` | | `chat.unshared_with_user` | `user` | `chat` | | `chat.visibility_updated` | `user` | `chat` | | `connection.permissions_enforcement_changed` | `system` | `connection` | | `license.activated` | `user` | `license` | | `license.activation_failed` | `user` | `license` | | `license.deactivated` | `user` | `license` | | `mcp_server.created` | `user` | `mcp_server` | | `mcp_server.deleted` | `user` | `mcp_server` | | `mcp_server.oauth_scopes_updated` | `user` | `mcp_server` | | `mcp_server.tool_permissions_updated` | `user` | `mcp_server` | | `oauth.authorization_granted` | `user` | `oauth_client` | | `oauth_client.access_revoked` | `user` | `oauth_client` | | `oauth_client.registered` | `anonymous` | `oauth_client` | | `oauth_token.exchange_failed` | `anonymous` | `oauth_client` | | `oauth_token.issued` | `oauth_client` | `user` | | `oauth_token.refresh_failed` | `anonymous` | `oauth_client` | | `oauth_token.refreshed` | `oauth_client` | `user` | | `oauth_token.revoked` | `oauth_client`, `anonymous` | `user` | | `org.credentials_login_updated` | `user`, `system` | `org` | | `org.email_code_login_updated` | `user`, `system` | `org` | | `org.invite_link_updated` | `user` | `org` | | `org.login_message_updated` | `user` | `org` | | `org.member_added` | `user`, `scim_token` | `user` | | `org.member_approval_required_updated` | `user`, `system` | `org` | | `org.member_deactivated` | `user`, `scim_token` | `user` | | `org.member_left` | `user`, `scim_token` | `user` | | `org.member_promoted_to_owner` | `user`, `scim_token` | `user` | | `org.member_reactivated` | `user`, `scim_token` | `user` | | `org.member_removed` | `user`, `scim_token` | `user` | | `org.owner_demoted_to_member` | `user`, `scim_token` | `user` | | `scim.disabled` | `user` | `org` | | `scim.enabled` | `user` | `org` | | `scim_token.auth_failed` | `anonymous`, `scim_token` | `org` | | `scim_token.created` | `user` | `scim_token` | | `scim_token.deleted` | `user` | `scim_token` | | `scoped_access_token.created` | `api_key` | `scoped_access_token` | | `scoped_access_token.deleted` | `api_key` | `scoped_access_token` | | `user.account_linked` | `user` | `account` | | `user.account_unlinked` | `user` | `account` | | `user.created` | `user`, `scim_token` | `user` | | `user.created_ask_chat` | `user` | `org` | | `user.creation_failed` | `user` | `user` | | `user.fetched_file_blame` | `user` | `org` | | `user.fetched_file_source` | `user` | `org` | | `user.fetched_file_tree` | `user` | `org` | | `user.invite_accept_failed` | `user` | `invite` | | `user.invite_accepted` | `user` | `invite` | | `user.invite_cancelled` | `user` | `invite` | | `user.invite_failed` | `user` | `org` | | `user.invites_created` | `user` | `org` | | `user.join_request_approve_failed` | `user` | `account_join_request` | | `user.join_request_approved` | `user` | `account_join_request` | | `user.list` | `user` | `org` | | `user.listed_repos` | `user` | `org` | | `user.mcp_server_connected` | `user` | `mcp_server` | | `user.mcp_server_connection_failed` | `user` | `mcp_server` | | `user.mcp_server_disconnected` | `user` | `mcp_server` | | `user.owner_created` | `user` | `org` | | `user.performed_code_search` | `user` | `org` | | `user.performed_find_references` | `user` | `org` | | `user.performed_goto_definition` | `user` | `org` | | `user.profile_updated` | `scim_token` | `user` | | `user.read` | `user` | `user` | | `user.sign_in_failed` | `anonymous`, `user` | `org` | | `user.signed_in` | `user` | `user` | | `user.signed_out` | `user` | `user` | ## Response schema ```json icon="brackets-curly" expandable wrap Audit log fetch response schema theme={null} { "$schema": "http://json-schema.org/draft-07/schema#", "title": "FetchAuditLogsResponse", "type": "array", "items": { "type": "object", "required": [ "id", "timestamp", "action", "actorId", "actorType", "actorLabel", "targetId", "targetType", "targetLabel", "sourcebotVersion", "metadata", "orgId" ], "properties": { "id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "action": { "type": "string" }, "actorId": { "type": "string" }, "actorType": { "type": "string", "enum": ["user", "api_key", "scim_token", "anonymous", "system", "oauth_client"] }, "actorLabel": { "type": ["string", "null"] }, "targetId": { "type": "string" }, "targetType": { "type": "string", "enum": ["user", "org", "file", "api_key", "account_join_request", "invite", "chat", "scim_token", "oauth_client", "account", "scoped_access_token", "mcp_server", "license", "connection"] }, "targetLabel": { "type": ["string", "null"] }, "sourcebotVersion": { "type": "string" }, "metadata": { "anyOf": [ { "type": "object", "properties": { "message": { "type": ["string", "null"] }, "api_key": { "type": "string" }, "scim_token": { "type": "string" }, "emails": { "type": "string" }, "source": { "type": "string" }, "enabled": { "type": "boolean" }, "envVar": { "type": "string" }, "reason": { "type": "string" }, "serverUrl": { "type": "string" }, "authMode": { "type": "string", "enum": ["static", "dynamic"] }, "scopes": { "type": "array", "items": { "type": "string" } }, "connectionCount": { "type": "integer" }, "before": { "type": "array", "items": { "type": "string" } }, "after": { "type": "array", "items": { "type": "string" } }, "invalidatedConnectionCount": { "type": "integer" }, "changes": { "type": "object", "additionalProperties": { "type": "string", "enum": ["ALLOWED", "NEEDS_APPROVAL", "DISABLED"] } }, "tier": { "type": ["string", "null"] }, "seatCap": { "type": ["integer", "null"] }, "email": { "type": "string" }, "field": { "type": "string", "enum": ["enforcePermissions", "enforcePermissionsForPublicRepos"] }, "oldValue": { "type": "boolean" }, "newValue": { "type": "boolean" }, "clearedCount": { "type": "integer" }, "provider": { "type": "string" }, "providerId": { "type": "string" }, "providerType": { "type": "string" }, "viaEmailMatch": { "type": "boolean" }, "tokenKind": { "type": "string", "enum": ["api_key", "oauth_access_token", "scoped_access_token", "access_token", "refresh_token"] }, "changedFields": { "type": "array", "items": { "type": "string", "enum": ["name", "email"] } }, "oldEmail": { "type": "string" }, "newEmail": { "type": "string" }, "repoIds": { "type": "array", "items": { "type": "integer" } }, "expiresAt": { "type": "string", "format": "date-time" }, "redirectUri": { "type": "string" }, "resource": { "type": ["string", "null"] }, "scope": { "type": "string" }, "revokedTokenCount": { "type": "integer" }, "name": { "type": "string" }, "redirectUris": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, { "type": "null" } ] }, "orgId": { "type": "integer" } }, "additionalProperties": false } } ``` # Access Settings Source: https://docs.sourcebot.dev/docs/configuration/auth/access-settings There are various settings to control how users access your Sourcebot deployment. # Member Approval By default, Sourcebot requires new members to be approved by an owner of the deployment. This section explains how approvals work and how to configure this behavior. ### Configuration Member approval can be configured by an owner of the deployment by navigating to **Settings -> Security**. ![Require approval for new members toggle in Settings → Access](https://mintcdn.com/sourcebot/qv2nmhsMgcWlGCuH/images/member_approval_toggle.png?fit=max\&auto=format\&n=qv2nmhsMgcWlGCuH\&q=85\&s=b77432fd9841eb3d2a3cb241d5ea3a16) ### Managing Requests If member approval is enabled, new members will be asked to submit a join request after signing up. They will not have access to the Sourcebot deployment until this request is approved by an owner. Owners can see and manage all pending join requests by navigating to **Settings -> Members**. ## Invite link If member approval is required, an owner of the deployment can enable an invite link. When enabled, users can use this invite link to register and be automatically added to the organization without approval: ![Enable invite links toggle in Settings → Access](https://mintcdn.com/sourcebot/qv2nmhsMgcWlGCuH/images/invite_link_toggle.png?fit=max\&auto=format\&n=qv2nmhsMgcWlGCuH\&q=85\&s=e9e6fa70717a15ecc234e76812212042) # Authentication Source: https://docs.sourcebot.dev/docs/configuration/auth/authentication > [!WARNING] > > If you're deploying Sourcebot behind a domain, you must set the [AUTH\_URL](/docs/configuration/environment-variables) environment variable. Choose how users sign in to your Sourcebot deployment. You can use email and password, email codes, or [single sign-on (SSO)](/docs/configuration/auth/sso). > **[Single sign-on (SSO)](/docs/configuration/auth/sso)** > > Let users sign in with GitHub, Google, Okta, or another identity provider. > **[Access settings](/docs/configuration/auth/access-settings)** > > Learn how to configure how members join your deployment. > **[SCIM provisioning](/docs/configuration/auth/scim)** > > Provision and deprovision organization members from your identity provider. > **[Roles and permissions](/docs/configuration/auth/roles-and-permissions)** > > Learn more about the different roles and permissions in Sourcebot. > **[FAQ](/docs/configuration/auth/faq)** > > Have a question about Sourcebot's auth system? We might have the answers here. # Email and password Email and password authentication is enabled by default. To enable or disable it, go to **Settings → Security** and toggle **Email login**. ![Email and password login setting in Settings → Security](https://mintcdn.com/sourcebot/qv2nmhsMgcWlGCuH/images/email_password_login_setting.png?fit=max\&auto=format\&n=qv2nmhsMgcWlGCuH\&q=85\&s=92b7974b8f625da742ee6a25d30ff0d5) # Email codes Users can sign in with a six-digit code sent to their email address. To enable email codes, configure [transactional emails](/docs/configuration/transactional-emails), then turn on **Email code** in **Settings → Security**. ![Email code login setting in Settings → Security](https://mintcdn.com/sourcebot/qv2nmhsMgcWlGCuH/images/email_code_login_setting.png?fit=max\&auto=format\&n=qv2nmhsMgcWlGCuH\&q=85\&s=17c902422570d5cdf1ff4427a5c416ff) # Session lifetime By default, session cookies remain valid for 30 days from the time they are issued, after which the user is signed out and must authenticate again. You can change this by setting the [`AUTH_SESSION_MAX_AGE_SECONDS`](/docs/configuration/environment-variables) environment variable to the desired lifetime in seconds. A session is guaranteed to remain valid for at least its configured lifetime. The JWT verifier applies a small clock-skew tolerance when checking expiry, so a session may continue to be accepted for a brief additional window past that point before it is rejected. # 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.gg/HDScTs3ptP) or [GitHub](https://github.com/sourcebot-dev/sourcebot/issues/new/choose) # FAQ Source: https://docs.sourcebot.dev/docs/configuration/auth/faq This page covers a range of frequently asked questions about Sourcebot's built-in authentication system. > **Can I disable the authentication system?** > > No, at this time it's not possible to disable the authentication system. If this is preventing you from deploying Sourcebot > within your organization please [reach out](https://www.sourcebot.dev/contact) > **I don't want to restrict access to my Sourcebot deployment, what should I do?** > > Every user must register an account within your Sourcebot deployment. However, this doesn't mean their access > is restricted. > > Unless member approval is required, anyone can sign up for an account on your deployment and immediately be granted access. > **Does any data related to authentication (emails, passwords, etc) leave my deployment?** > > **No data related to authentication (or your code) leaves your deployment**. Authentication is handled > purely by your deployment and the authentication providers you configure. > > This data does not leave your device and is stored within in the database managed by your deployment. If you're > using credential login, passwords are encrypted at rest and in transit. > **I'm deploying Sourcebot behind an identity proxy, do I still need to create an account in Sourcebot?** > > \[!NOTE] Please note that IAP bridges are an enterprise feature > Sourcebot supports connecting your identity proxy directly into the built-in auth system using an IAP bridge. This allows Sourcebot to > register and authenticate automatically on a successful identity proxy log in. > > Sourcebot currently supports [GCP IAP](/docs/configuration/auth/sso#google-cloud-iap). If you're using a different IAP > and require support, please [reach out](https://www.sourcebot.dev/contact) > **How does Sourcebot implement authentication?** > > Sourcebot uses [Auth.js](https://authjs.dev/) as its underlying authentication framework. Auth.js provides authentication providers > (credentials, Google, GitHub, etc) and an interface to enable user registration and log in. Internally, Auth.js uses JWT to provide > Sourcebot secure and reliable information about user authentication. Have a question that's not answered here? Submit an issue on [GitHub](https://github.com/sourcebot-dev/sourcebot/issues/new/choose) and we'll get back to you as soon as we can. # Members and roles Source: https://docs.sourcebot.dev/docs/configuration/auth/roles-and-permissions Sourcebot provides different role types to help you control access and permissions across your organization. | Role | Permission | | :- | :- | | `Owner` | Owners have full administrative control over all organization-level settings, including user management, access control, billing, and audit logs, in addition to all permissions a member can perform. | | `Member` | Members have access and to use all standard features, such as code search, ask, mcp, etc., as well as their account settings. Members **cannot access** organization-level administration pages. | Note that when [permission syncing](/docs/features/permission-syncing) is enabled, users will only be able to view repositories they have access to. This applies to all roles, **including Owners**. > [!NOTE] > > On the Basic plan, all signed-in users are given the `Owner` role. ## Default role assignment When a user joins your organization, they are assigned a default role. This assignment, and the ability to [manage the user's role](#managing-member-roles) afterwards, depends on [your plan](/docs/activating-a-subscription): | Plan | Default role | Role management | | :- | :- | :- | | **Basic** | `Owner` | Not available. A user's role cannot be changed. | | **Paid** | `Member` | Available. Owners can [promote or demote](#managing-member-roles) members. | ## Managing member roles > [!NOTE] > > Role management is only available in a paid plan. Please activate a [license key](/docs/activating-a-subscription) to use this feature. Owners can change the role of any user in the organization from **Settings → Members**. This lets you control who has administrative access by promoting trusted members to `Owner`, and scoping access back down to `Member` when administrative responsibilities change. ![Members settings page showing team members and their roles](https://mintcdn.com/sourcebot/qv2nmhsMgcWlGCuH/images/managing_owners.png?fit=max\&auto=format\&n=qv2nmhsMgcWlGCuH\&q=85\&s=3ff96da5ac9470dba3809d22c943fd54) ### Promoting a member to owner To promote a member, click the action menu (three dots) next to their name in the members list and select **Promote to owner**. The member will immediately gain full administrative access. ![Dropdown menu showing Promote to owner option for a member](https://mintcdn.com/sourcebot/qv2nmhsMgcWlGCuH/images/promote_to_owner.png?fit=max\&auto=format\&n=qv2nmhsMgcWlGCuH\&q=85\&s=e072c9a223c2a2d9fe553a09ecdfdb8b) ### Demoting an owner to member To demote an owner, click the action menu next to their name and select **Demote to member**. Owners can also demote themselves to step down from the role. The last remaining owner of an organization cannot be demoted - at least one owner must exist at all times. ![Dropdown menu showing Demote to member option for an owner](https://mintcdn.com/sourcebot/qv2nmhsMgcWlGCuH/images/demote_to_member.png?fit=max\&auto=format\&n=qv2nmhsMgcWlGCuH\&q=85\&s=e20d8364993535ae7555e7a6ba1a87fc) ### Leaving an organization as an owner An owner can leave the organization as long as at least one other owner exists. If you are the last owner, you must promote another member to owner before leaving. ![Dropdown menu showing Leave organization option for an owner](https://mintcdn.com/sourcebot/qv2nmhsMgcWlGCuH/images/owner_leave_org.png?fit=max\&auto=format\&n=qv2nmhsMgcWlGCuH\&q=85\&s=b0ba8bce7c78cdee56f3a1349fa8953b) # SCIM Source: https://docs.sourcebot.dev/docs/configuration/auth/scim SCIM, or *System for Cross-domain Identity Management* allows for the automation of user provisioning for your Sourcebot organization. ![SCIM provisioning settings in Sourcebot showing the enable toggle, connector base URL, and SCIM token list](https://mintcdn.com/sourcebot/DazASi3htq5tl1AS/images/scim_provisioning_settings.png?fit=max\&auto=format\&n=DazASi3htq5tl1AS\&q=85\&s=2761e24353091a4decc539fc1de4db42) > [!NOTE] > > SCIM provisioning is only available in a paid plan. Please activate a [license key](/docs/activating-a-subscription) to use this feature. ## Overview SCIM provisioning lets your identity provider manage Sourcebot organization membership automatically. When enabled, your identity provider becomes the source of truth for who should have access to your Sourcebot organization. Sourcebot supports SCIM 2.0 user provisioning for identity providers such as Okta and Microsoft Entra ID. ## Configure 1. Navigate to **Settings -> Security**. 2. Under the "SCIM provisioning" section, toggle the option to enable SCIM. 3. You can now get your **SCIM connector base URL** and generate a **SCIM Bearer auth token**. These values will be needed to configure SCIM in your identity provider. > [!NOTE] > > When SCIM provisioning is enabled, Admins will **not** be able to manage users from within Sourcebot as they will be kept up to date through your identity provider. Role assignments can still be managed within Sourcebot. ### IdP-specific configuration notes **Okta** > [!NOTE] > > Okta does not support SCIM in an OIDC app integration. To work around this, two apps need to be created: > > 1. An OIDC app used for SSO. > 2. A SAML provisioning-only app. The SSO portion of the app should not need to be functional. > > [Learn more](https://support.okta.com/help/s/article/configure-scim-for-a-custom-oidc-app). * Follow [these instructions](/docs/configuration/auth/sso#okta) to setup a Okta OIDC app and configure it as a SSO provider in Sourcebot. * In Okta admin pages, create a SAML 2.0 application. This app will be used for provisioning-only and will not be used for SSO. The sign-on URL and audience URI can be set to the base URL of your deployment. * In the General tab, click Edit and choose SCIM in the Provisioning section and Save. * In the Provisioning tab, enter the SCIM Base connector URL from Sourcebot. * For the Unique identifier field for users section enter **userName** * For Supported provisioning actions, enable "Push New Users" and "Push Profile Updates" * For Authentication mode field, choose HTTP Header and enter your SCIM token generated in Sourcebot. You can now test the configuration and save * Lastly, return to the Provisioning tab in Okta and edit your settings under “To App” to enable the SCIM functionality needed for your Sourcebot application (Create, Update and Deactivate users) ![Okta provisioning To App settings showing Create Users, Update User Attributes, and Deactivate Users enabled](https://mintcdn.com/sourcebot/DazASi3htq5tl1AS/images/okta_scim_to_app_provisioning.png?fit=max\&auto=format\&n=DazASi3htq5tl1AS\&q=85\&s=54ef0462b4836499a3cb53fe62438736) ## User lifecycle Sourcebot represents organization users with three membership states: | Sourcebot state | Access | Billing | | - | - | - | | Pending | Can access the organization after signing in | Not billed | | Active | Can access the organization | Billed | | Suspended | Cannot access the organization | Not billed | When a user is provisioned through SCIM, Sourcebot creates or restores their organization membership. New SCIM-provisioned users appear as **Pending** until they sign in and access the organization for the first time. When a pending user signs in, Sourcebot moves them to **Active** and they count toward billing. On deployments with a hard seat cap, the user can only become active if a seat is available. When your identity provider deactivates a user by sending `active: false`, Sourcebot marks the user as **Suspended**. Suspended users cannot access the organization, and Sourcebot revokes their active sessions, API keys, and OAuth tokens. If your identity provider reactivates the user by sending `active: true`, Sourcebot restores their membership as **Pending**. They become **Active** and billable again only after they sign in and access the organization. ## Roles SCIM does not assign Sourcebot [roles](/docs/configuration/auth/roles-and-permissions). Users created through SCIM are added with the **Member** role. Owners can promote active members to owner, or demote owners to member, from **Settings -> Members**. Sourcebot prevents changes that would leave the organization without an active owner. ## Supported attributes Sourcebot stores this subset of SCIM user attributes: | SCIM attribute | Sourcebot behavior | | - | - | | `userName` | User email address | | `emails` | User email address; the primary email is preferred | | `name.formatted` | Display name | | `displayName` | Display name fallback | | `active` | Unsuspended or suspended membership state | | `externalId` | Stored IdP external identifier | Additional attributes may be sent by your identity provider, but Sourcebot ignores attributes it does not use. ## FAQ > **What identity providers do you support?** > > SCIM provisioning should work with most identity providers that support SCIM user provisioning, but it has only been tested with Okta. > **What version of SCIM do you support?** > > Sourcebot supports SCIM 2.0. > **When do SCIM-created users become billable seats?** > > SCIM-created or reactivated users become billable seats after they sign in and access the organization. Until then, they appear as pending and do not count toward billing. Suspended users also do not count toward billing. # Single sign-on (SSO) Source: https://docs.sourcebot.dev/docs/configuration/auth/sso Set up **single sign-on (SSO)** so users can sign in to Sourcebot with an identity provider such as GitHub, Google, or Okta. Choose your provider below for setup instructions. For email and password or email-code login, see [Authentication](/docs/configuration/auth/authentication). To connect external accounts for permission syncing without using them for sign-in, see [Account linking](#account-linking). # Configure SSO Add your providers to the top-level `identityProviders` array in your [config file](/docs/configuration/config-file). Set `purpose` to `"sso"` to use a provider for sign-in: ```json wrap icon="code" Example config with GitHub and Google SSO providers theme={null} { "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", "identityProviders": [ { "provider": "github", "purpose": "sso", "clientId": { "env": "GITHUB_IDENTITY_PROVIDER_CLIENT_ID" }, "clientSecret": { "env": "GITHUB_IDENTITY_PROVIDER_CLIENT_SECRET" } }, { "provider": "google", "purpose": "sso", "clientId": { "env": "GOOGLE_IDENTITY_PROVIDER_CLIENT_ID" }, "clientSecret": { "env": "GOOGLE_IDENTITY_PROVIDER_CLIENT_SECRET" } } ] } ``` Secret values (such as `clientId` and `clientSecret`) can be provided as environment variables or Google Cloud secrets via [tokens](/docs/configuration/config-file#tokens). To configure **multiple providers of the same type**, see [Configuring multiple providers of the same type](#configuring-multiple-providers-of-the-same-type). # Supported identity providers Sourcebot uses [Auth.js](https://authjs.dev/) to connect to external identity providers. If there's a provider supported by Auth.js that you don't see below, please submit a [feature request](https://github.com/sourcebot-dev/sourcebot/issues) to have it added. ### GitHub [Auth.js GitHub Provider Docs](https://authjs.dev/getting-started/providers/github) A GitHub connection can be used for [authentication](/docs/configuration/auth/authentication) and/or [permission syncing](/docs/features/permission-syncing). This is controlled using the `purpose` field in the GitHub identity provider config. > **instructions** > > **1. Register an Oauth Client** > > To begin, you must register an Oauth client in GitHub to facilitate the identity provider connection. You can do this by creating a **GitHub App** or a **GitHub OAuth App**. Either > one works, but the **GitHub App** is the [recommended mechanism](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps). > > The result of registering an OAuth client is a `CLIENT_ID` and `CLIENT_SECRET` which you'll provide to Sourcebot. > > **GitHub App** > > \[!NOTE] You don't need to install the app to use it as an external identity provider > Follow [this guide](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) to register a new GitHub App. > > When asked to provide a callback url, provide `/api/auth/callback/github` (ex. [https://sourcebot.coolcorp.com/api/auth/callback/github](https://sourcebot.coolcorp.com/api/auth/callback/github)) > > ![GitHub App callback URL configuration](https://mintcdn.com/sourcebot/5GTKuw6o2zlxMh3w/images/github_app_callback_url.png?fit=max\&auto=format\&n=5GTKuw6o2zlxMh3w\&q=85\&s=bb3f358ad574890d2dad67fb0f0c0764) > > Select "Request user authorization (OAuth) during installation" > > ![GitHub App request user authorization during installation](https://mintcdn.com/sourcebot/5GTKuw6o2zlxMh3w/images/github_app_request_user_auth.png?fit=max\&auto=format\&n=5GTKuw6o2zlxMh3w\&q=85\&s=4cc957b88f3b3749ad2357aef83010fe) > > Set the following fine-grained permissions in the GitHub App: > > * `“Email addresses” account permissions (read)` > > ![Email addresses account permission set to Read-only](https://mintcdn.com/sourcebot/5GTKuw6o2zlxMh3w/images/github_app_perm_email.png?fit=max\&auto=format\&n=5GTKuw6o2zlxMh3w\&q=85\&s=760701a7a956729ef3db73e7034ded2e) > * `"Metadata" repository permissions (read)` (only needed if using [permission syncing](/docs/features/permission-syncing)) > > ![Metadata repository permission set to Read-only](https://mintcdn.com/sourcebot/5GTKuw6o2zlxMh3w/images/github_app_perm_metadata.png?fit=max\&auto=format\&n=5GTKuw6o2zlxMh3w\&q=85\&s=6fc0fea56471532960967e93867545d1) > * `"Contents" repository permissions (read)` (only needed if using the app to [authenticate a connection](/docs/connections/github#authenticating-with-github)) > > ![Contents repository permission set to Read-only](https://mintcdn.com/sourcebot/5GTKuw6o2zlxMh3w/images/github_app_perm_contents.png?fit=max\&auto=format\&n=5GTKuw6o2zlxMh3w\&q=85\&s=c159ca100148714d0be1824f30ec163b) > > **GitHub OAuth App** > > Follow [this guide](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) by GitHub to create an OAuth App. > > When asked to provide a callback url, provide `/api/auth/callback/github` (ex. [https://sourcebot.coolcorp.com/api/auth/callback/github](https://sourcebot.coolcorp.com/api/auth/callback/github)) > > If [permission syncing](/docs/features/permission-syncing#github) is enabled, also enable the `repo` scope. > > **2. Define environment variables** > > To provide Sourcebot the client id and secret for your OAuth client you must set them as environment variables. These can be named whatever you like > (ex. `GITHUB_IDENTITY_PROVIDER_CLIENT_ID` and `GITHUB_IDENTITY_PROVIDER_CLIENT_SECRET`) > > **3. Define the identity provider config** > > Finally, pass the client id and secret to Sourcebot by defining a `identityProvider` object in the [config file](/docs/configuration/config-file): > > ```json wrap icon="code" theme={null} > { > "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", > "identityProviders": [ > { > "provider": "github", > "purpose": "sso", > "clientId": { > "env": "YOUR_CLIENT_ID_ENV_VAR" > }, > "clientSecret": { > "env": "YOUR_CLIENT_SECRET_ENV_VAR" > }, > // Optional: for self-hosted GitHub Enterprise Server instances > "baseUrl": "https://github.example.com" > } > ] > } > ``` ### GitLab [Auth.js GitLab Provider Docs](https://authjs.dev/getting-started/providers/gitlab) A GitLab connection can be used for [authentication](/docs/configuration/auth/authentication) and/or [permission syncing](/docs/features/permission-syncing). This is controlled using the `purpose` field in the GitLab identity provider config. > **instructions** > > **1. Register an OAuth Application** > > To begin, you must register an OAuth application in GitLab to facilitate the identity provider connection. > > Follow [this guide](https://docs.gitlab.com/integration/oauth_provider/) by GitLab to create an OAuth application. > > When configuring your application: > > * Set the callback URL to `/api/auth/callback/gitlab` (ex. [https://sourcebot.coolcorp.com/api/auth/callback/gitlab](https://sourcebot.coolcorp.com/api/auth/callback/gitlab)) > * Enable the `read_user` scope > * If [permission syncing](/docs/features/permission-syncing#gitlab) is enabled, also enable the `read_api` scope > > The result of registering an OAuth application is an `APPLICATION_ID` (`CLIENT_ID`) and `SECRET` (`CLIENT_SECRET`) which you'll provide to Sourcebot. > > **2. Define environment variables** > > To provide Sourcebot the client id and secret for your OAuth application you must set them as environment variables. These can be named whatever you like > (ex. `GITLAB_IDENTITY_PROVIDER_CLIENT_ID` and `GITLAB_IDENTITY_PROVIDER_CLIENT_SECRET`) > > **3. Define the identity provider config** > > Finally, pass the client id and secret to Sourcebot by defining a `identityProvider` object in the [config file](/docs/configuration/config-file): > > ```json wrap icon="code" theme={null} > { > "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", > "identityProviders": [ > { > "provider": "gitlab", > "purpose": "sso", > "clientId": { > "env": "YOUR_CLIENT_ID_ENV_VAR" > }, > "clientSecret": { > "env": "YOUR_CLIENT_SECRET_ENV_VAR" > }, > // Optional: for self-hosted GitLab instances > "baseUrl": "https://gitlab.example.com" > } > ] > } > ``` ### Bitbucket Cloud [Auth.js Bitbucket Provider Docs](https://authjs.dev/getting-started/providers/bitbucket) A Bitbucket Cloud connection can be used for [authentication](/docs/configuration/auth/authentication) and/or [permission syncing](/docs/features/permission-syncing). This is controlled using the `purpose` field in the Bitbucket Cloud identity provider config. > **instructions** > > **1. Register an OAuth Consumer** > > To begin, you must register an OAuth consumer in Bitbucket to facilitate the identity provider connection. > > Navigate to your Bitbucket workspace settings at `https://bitbucket.org//workspace/settings/api` and create a new **OAuth consumer** under the **OAuth consumers** section. > > When configuring your consumer: > > * Set the callback URL to `/api/auth/callback/bitbucket-cloud` (ex. [https://sourcebot.coolcorp.com/api/auth/callback/bitbucket-cloud](https://sourcebot.coolcorp.com/api/auth/callback/bitbucket-cloud)) > * Enable **Account: Read** > * If [permission syncing](/docs/features/permission-syncing#bitbucket-cloud) is enabled, also enable **Repositories: Read** > > The result of creating an OAuth consumer is a `Key` (`CLIENT_ID`) and `Secret` (`CLIENT_SECRET`) which you'll provide to Sourcebot. > > **2. Define environment variables** > > To provide Sourcebot the client id and secret for your OAuth consumer you must set them as environment variables. These can be named whatever you like > (ex. `BITBUCKET_CLOUD_IDENTITY_PROVIDER_CLIENT_ID` and `BITBUCKET_CLOUD_IDENTITY_PROVIDER_CLIENT_SECRET`) > > **3. Define the identity provider config** > > Finally, pass the client id and secret to Sourcebot by defining a `identityProvider` object in the [config file](/docs/configuration/config-file): > > ```json wrap icon="code" theme={null} > { > "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", > "identityProviders": [ > { > "provider": "bitbucket-cloud", > "purpose": "sso", > "clientId": { > "env": "YOUR_CLIENT_ID_ENV_VAR" > }, > "clientSecret": { > "env": "YOUR_CLIENT_SECRET_ENV_VAR" > } > } > ] > } > ``` ### Bitbucket Server A Bitbucket Server (Data Center) connection can be used for [authentication](/docs/configuration/auth/authentication) and/or [permission syncing](/docs/features/permission-syncing). This is controlled using the `purpose` field in the Bitbucket Server identity provider config. > **instructions** > > **1. Register an OAuth 2.0 Application** > > To begin, you must register an OAuth 2.0 application in your Bitbucket Server instance to facilitate the identity provider connection. > > In your Bitbucket Server admin panel, navigate to **Administration → Application Links** and create a new incoming external application link. > > When configuring your application: > > * Set the redirect URL to `/api/auth/callback/bitbucket-server` (ex. [https://sourcebot.coolcorp.com/api/auth/callback/bitbucket-server](https://sourcebot.coolcorp.com/api/auth/callback/bitbucket-server)) > * If [permission syncing](/docs/features/permission-syncing#bitbucket-data-center) is enabled, also enable the `REPO_READ` scope > > The result of creating the application is a `CLIENT_ID` and `CLIENT_SECRET` which you'll provide to Sourcebot. > > **2. Define environment variables** > > To provide Sourcebot the client id and secret for your OAuth application you must set them as environment variables. These can be named whatever you like > (ex. `BITBUCKET_SERVER_IDENTITY_PROVIDER_CLIENT_ID` and `BITBUCKET_SERVER_IDENTITY_PROVIDER_CLIENT_SECRET`) > > **3. Define the identity provider config** > > Finally, pass the client id, client secret, and your Bitbucket Server base URL to Sourcebot by defining a `identityProvider` object in the [config file](/docs/configuration/config-file): > > ```json wrap icon="code" theme={null} > { > "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", > "identityProviders": [ > { > "provider": "bitbucket-server", > "purpose": "sso", > "baseUrl": "https://bitbucket.example.com", > "clientId": { > "env": "YOUR_CLIENT_ID_ENV_VAR" > }, > "clientSecret": { > "env": "YOUR_CLIENT_SECRET_ENV_VAR" > } > } > ] > } > ``` ### Google [Auth.js Google Provider Docs](https://authjs.dev/getting-started/providers/google) A Google connection can be used for [authentication](/docs/configuration/auth/authentication). > **instructions** > > **1. Register an OAuth Client** > > To begin, you must register an OAuth client in Google Cloud Console to facilitate the identity provider connection. > > Follow [this guide](https://support.google.com/cloud/answer/6158849) by Google to create OAuth 2.0 credentials. > > When configuring your OAuth client: > > * Set the application type to "Web application" > * Add `/api/auth/callback/google` to the authorized redirect URIs (ex. [https://sourcebot.coolcorp.com/api/auth/callback/google](https://sourcebot.coolcorp.com/api/auth/callback/google)) > > The result of creating OAuth credentials is a `CLIENT_ID` and `CLIENT_SECRET` which you'll provide to Sourcebot. > > **2. Define environment variables** > > To provide Sourcebot the client id and secret for your OAuth client you must set them as environment variables. These can be named whatever you like > (ex. `GOOGLE_IDENTITY_PROVIDER_CLIENT_ID` and `GOOGLE_IDENTITY_PROVIDER_CLIENT_SECRET`) > > **3. Define the identity provider config** > > Finally, pass the client id and secret to Sourcebot by defining a `identityProvider` object in the [config file](/docs/configuration/config-file): > > ```json wrap icon="code" theme={null} > { > "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", > "identityProviders": [ > { > "provider": "google", > "purpose": "sso", > "clientId": { > "env": "YOUR_CLIENT_ID_ENV_VAR" > }, > "clientSecret": { > "env": "YOUR_CLIENT_SECRET_ENV_VAR" > } > } > ] > } > ``` ### Okta [Auth.js Okta Provider Docs](https://authjs.dev/getting-started/providers/okta) An Okta connection can be used for [authentication](/docs/configuration/auth/authentication). > **instructions** > > **1. Register an OAuth Application** > > To begin, you must register an OAuth application in Okta to facilitate the identity provider connection. > > Follow [this guide](https://developer.okta.com/docs/guides/implement-oauth-for-okta/main/) by Okta to create an OAuth application. > > When configuring your application: > > * Set the application type to "Web Application" > * Add `/api/auth/callback/okta` to the sign-in redirect URIs (ex. [https://sourcebot.coolcorp.com/api/auth/callback/okta](https://sourcebot.coolcorp.com/api/auth/callback/okta)) > > The result of creating an OAuth application is a `CLIENT_ID`, `CLIENT_SECRET`, and `ISSUER` URL which you'll provide to Sourcebot. > > **2. Define environment variables** > > To provide Sourcebot the client id, client secret, and issuer for your OAuth application you must set them as environment variables. These can be named whatever you like > (ex. `OKTA_IDENTITY_PROVIDER_CLIENT_ID`, `OKTA_IDENTITY_PROVIDER_CLIENT_SECRET`, and `OKTA_IDENTITY_PROVIDER_ISSUER`) > > **3. Define the identity provider config** > > Finally, pass the client id, client secret, and issuer to Sourcebot by defining a `identityProvider` object in the [config file](/docs/configuration/config-file): > > ```json wrap icon="code" theme={null} > { > "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", > "identityProviders": [ > { > "provider": "okta", > "purpose": "sso", > "clientId": { > "env": "YOUR_CLIENT_ID_ENV_VAR" > }, > "clientSecret": { > "env": "YOUR_CLIENT_SECRET_ENV_VAR" > }, > "issuer": { > "env": "YOUR_ISSUER_ENV_VAR" > } > } > ] > } > ``` ### Keycloak [Auth.js Keycloak Provider Docs](https://authjs.dev/getting-started/providers/keycloak) A Keycloak connection can be used for [authentication](/docs/configuration/auth/authentication). > **instructions** > > **1. Register an OAuth Client** > > To begin, you must register an OAuth client in Keycloak to facilitate the identity provider connection. > > Follow [this guide](https://www.keycloak.org/docs/latest/server_admin/#_oidc_clients) by Keycloak to create an OpenID Connect client. > > When configuring your client: > > * Set the client protocol to "openid-connect" > * Set the access type to "confidential" > * Add `/api/auth/callback/keycloak` to the valid redirect URIs (ex. [https://sourcebot.coolcorp.com/api/auth/callback/keycloak](https://sourcebot.coolcorp.com/api/auth/callback/keycloak)) > > The result of creating an OAuth client is a `CLIENT_ID`, `CLIENT_SECRET`, and an `ISSUER` URL (typically in the format `https:///realms/`) which you'll provide to Sourcebot. > > **2. Define environment variables** > > To provide Sourcebot the client id, client secret, and issuer for your OAuth client you must set them as environment variables. These can be named whatever you like > (ex. `KEYCLOAK_IDENTITY_PROVIDER_CLIENT_ID`, `KEYCLOAK_IDENTITY_PROVIDER_CLIENT_SECRET`, and `KEYCLOAK_IDENTITY_PROVIDER_ISSUER`) > > **3. Define the identity provider config** > > Finally, pass the client id, client secret, and issuer to Sourcebot by defining a `identityProvider` object in the [config file](/docs/configuration/config-file): > > ```json wrap icon="code" theme={null} > { > "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", > "identityProviders": [ > { > "provider": "keycloak", > "purpose": "sso", > "clientId": { > "env": "YOUR_CLIENT_ID_ENV_VAR" > }, > "clientSecret": { > "env": "YOUR_CLIENT_SECRET_ENV_VAR" > }, > "issuer": { > "env": "YOUR_ISSUER_ENV_VAR" > } > } > ] > } > ``` ### Azure DevOps Cloud [Microsoft Entra OAuth for Azure DevOps Docs](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/entra-oauth?view=azure-devops) > [!NOTE] > > This provider supports Azure DevOps Cloud with organizational Microsoft Entra accounts. Azure DevOps Server and personal Microsoft accounts are not supported. > **instructions** > > **1. Register an OAuth Application** > > To begin, you must register an OAuth application in the Microsoft Entra tenant connected to your Azure DevOps organizations. > > Follow [this guide](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) by Microsoft to register an application. > > When configuring your application: > > * Under "Supported account types", select "Single tenant only" (labeled "Accounts in this organizational directory only" in some versions of the portal) > * Under "Authentication", add a platform and select "Web" > * Set the redirect URI to `/api/auth/callback/azuredevops` (ex. [https://sourcebot.coolcorp.com/api/auth/callback/azuredevops](https://sourcebot.coolcorp.com/api/auth/callback/azuredevops)). Entra requires an `https://` redirect URI unless the host is `localhost` > > ![Microsoft Entra app registration with single tenant account type and Web redirect URI](https://mintcdn.com/sourcebot/nOBtg1FMTNKcRT8R/images/ado_entra_register_app.png?fit=max\&auto=format\&n=nOBtg1FMTNKcRT8R\&q=85\&s=0dafb8684b9edfaf626e9594453c6979) > * Under "Certificates & secrets", create a new client secret > > ![Microsoft Entra add a client secret panel](https://mintcdn.com/sourcebot/nOBtg1FMTNKcRT8R/images/ado_entra_client_secret.png?fit=max\&auto=format\&n=nOBtg1FMTNKcRT8R\&q=85\&s=9d7d4cd9849f4628f94f0de02cae28e9) > * Under "API permissions", add the **Azure DevOps** delegated permission **Code (Read)** (`vso.code`), and grant consent according to your tenant's policies. Sourcebot requests the app's configured Azure DevOps permissions through the `.default` scope, so only add the permissions you need > > ![Azure DevOps delegated vso.code permission selected in Microsoft Entra](https://mintcdn.com/sourcebot/nOBtg1FMTNKcRT8R/images/ado_entra_api_permissions.png?fit=max\&auto=format\&n=nOBtg1FMTNKcRT8R\&q=85\&s=9d8e0c434b6135c7c312b873618c6e16) > > The result of registering an application is a `CLIENT_ID` (Application ID), `CLIENT_SECRET`, and `TENANT_ID` (Directory ID) which you'll provide to Sourcebot. > > **2. Define environment variables** > > To provide Sourcebot the client id and secret for your OAuth application you must set them as environment variables. These can be named whatever you like > (ex. `AZURE_DEVOPS_IDENTITY_PROVIDER_CLIENT_ID` and `AZURE_DEVOPS_IDENTITY_PROVIDER_CLIENT_SECRET`) > > **3. Define the identity provider config** > > Finally, pass the client id, client secret, and tenant id to Sourcebot by defining a `identityProvider` object in the [config file](/docs/configuration/config-file): > > ```json wrap icon="code" theme={null} > { > "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", > "identityProviders": [ > { > "provider": "azuredevops", > "purpose": "account_linking", > "tenantId": "YOUR_ENTRA_TENANT_ID", > "clientId": { > "env": "YOUR_CLIENT_ID_ENV_VAR" > }, > "clientSecret": { > "env": "YOUR_CLIENT_SECRET_ENV_VAR" > }, > // Optional: require users to link an Azure DevOps account > "accountLinkingRequired": true > } > ] > } > ``` > > Use `"purpose": "account_linking"` to keep your existing sign-in provider and let users connect Azure DevOps through **Settings → Linked Accounts**. Use `"purpose": "sso"` to sign in and authorize Azure DevOps access in one flow. ### Microsoft Entra ID (Azure AD) [Auth.js Microsoft Entra ID Provider Docs](https://authjs.dev/getting-started/providers/microsoft-entra-id) A Microsoft Entra ID connection can be used for [authentication](/docs/configuration/auth/authentication). > [!NOTE] > > Microsoft renamed Azure Active Directory (Azure AD) to Microsoft Entra ID in 2023. If you have an existing Azure AD setup, these instructions will work for you. The underlying authentication infrastructure is the same. > **instructions** > > **1. Register an OAuth Application** > > To begin, you must register an OAuth application in Microsoft Entra ID (formerly Azure Active Directory) to facilitate the identity provider connection. > > Follow [this guide](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) by Microsoft to register an application. > > When configuring your application: > > * Under "Authentication", add a platform and select "Web" > * Set the redirect URI to `/api/auth/callback/microsoft-entra-id` (ex. [https://sourcebot.coolcorp.com/api/auth/callback/microsoft-entra-id](https://sourcebot.coolcorp.com/api/auth/callback/microsoft-entra-id)) > * Under "Certificates & secrets", create a new client secret > > The result of registering an application is a `CLIENT_ID` (Application ID), `CLIENT_SECRET`, and `TENANT_ID` which you'll use to construct the issuer URL. > > **2. Define environment variables** > > To provide Sourcebot the client id, client secret, and issuer for your OAuth application you must set them as environment variables. These can be named whatever you like > (ex. `MICROSOFT_ENTRA_ID_IDENTITY_PROVIDER_CLIENT_ID`, `MICROSOFT_ENTRA_ID_IDENTITY_PROVIDER_CLIENT_SECRET`, and `MICROSOFT_ENTRA_ID_IDENTITY_PROVIDER_ISSUER`) > > The issuer URL should be in the format: `https://login.microsoftonline.com//v2.0` > > **3. Define the identity provider config** > > Finally, pass the client id, client secret, and issuer to Sourcebot by defining a `identityProvider` object in the [config file](/docs/configuration/config-file): > > ```json wrap icon="code" theme={null} > { > "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", > "identityProviders": [ > { > "provider": "microsoft-entra-id", > "purpose": "sso", > "clientId": { > "env": "YOUR_CLIENT_ID_ENV_VAR" > }, > "clientSecret": { > "env": "YOUR_CLIENT_SECRET_ENV_VAR" > }, > "issuer": { > "env": "YOUR_ISSUER_ENV_VAR" > } > } > ] > } > ``` ### Authentik [Auth.js Authentik Provider Docs](https://authjs.dev/getting-started/providers/authentik) An Authentik connection can be used for [authentication](/docs/configuration/auth/authentication). > **instructions** > > **1. Create a OAuth2/OpenID Connect application** > > To begin, you must create a OAuth2/OpenID Connect application in Authentik. For more information, see the [Authentik documentation](https://docs.goauthentik.io/add-secure-apps/applications/manage_apps/#create-an-application-and-provider-pair). > > When configuring your application: > > * Set the provider type to "OAuth2/OpenID Connect" > * Set the client type to "Confidential" > * Add `/api/auth/callback/authentik` to the redirect URIs (ex. [https://sourcebot.coolcorp.com/api/auth/callback/authentik](https://sourcebot.coolcorp.com/api/auth/callback/authentik)) > > After creating the application, open the application details to obtain the client id, client secret, and issuer URL (typically in the format `https:///application/o//`). > > **2. Define environment variables** > > The client id, secret, and issuer URL are provided to Sourcebot via environment variables. These can be named whatever you like > (ex. `AUTHENTIK_IDENTITY_PROVIDER_CLIENT_ID`, `AUTHENTIK_IDENTITY_PROVIDER_CLIENT_SECRET`, and `AUTHENTIK_IDENTITY_PROVIDER_ISSUER`) > > **3. Define the identity provider config** > > Create a `identityProvider` object in the [config file](/docs/configuration/config-file) with the following fields: > > ```json wrap icon="code" theme={null} > { > "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", > "identityProviders": [ > { > "provider": "authentik", > "purpose": "sso", > "clientId": { > "env": "AUTHENTIK_IDENTITY_PROVIDER_CLIENT_ID" > }, > "clientSecret": { > "env": "AUTHENTIK_IDENTITY_PROVIDER_CLIENT_SECRET" > }, > "issuer": { > "env": "AUTHENTIK_IDENTITY_PROVIDER_ISSUER" > } > } > ] > } > ``` ### JumpCloud A JumpCloud connection can be used for [authentication](/docs/configuration/auth/authentication). JumpCloud supports OIDC (OpenID Connect), which Sourcebot uses to authenticate users. > **instructions** > > **1. Create an SSO Application in JumpCloud** > > To begin, you must create an SSO application in JumpCloud to facilitate the identity provider connection. For more information, see the [JumpCloud OIDC documentation](https://jumpcloud.com/support/sso-with-oidc). > > When configuring your application: > > * Set the SSO type to "OIDC" > * Set the **Token Endpoint Authentication Method** to `client_secret_basic`. JumpCloud defaults to `client_secret_post`, but Sourcebot requires `client_secret_basic`. > * Add `/api/auth/callback/jumpcloud` to the redirect URIs (ex. [https://sourcebot.coolcorp.com/api/auth/callback/jumpcloud](https://sourcebot.coolcorp.com/api/auth/callback/jumpcloud)) > * Set the login URL to `/login` > > After creating the application, note the `CLIENT_ID` and `CLIENT_SECRET`. The issuer URL is typically `https://oauth.id.jumpcloud.com`. > > **2. Define environment variables** > > The client id, secret, and issuer URL are provided to Sourcebot via environment variables. These can be named whatever you like > (ex. `JUMPCLOUD_IDENTITY_PROVIDER_CLIENT_ID`, `JUMPCLOUD_IDENTITY_PROVIDER_CLIENT_SECRET`, and `JUMPCLOUD_IDENTITY_PROVIDER_ISSUER`) > > You must also set the `AUTH_SECRET` environment variable. Generate one with `openssl rand -base64 33` and pass it to your Sourcebot deployment. While `AUTH_SECRET` is auto-generated if not provided, it must be explicitly set for SSO to work reliably across restarts. > > **3. Define the identity provider config** > > Create a `identityProvider` object in the [config file](/docs/configuration/config-file) with the following fields: > > ```json wrap icon="code" theme={null} > { > "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", > "identityProviders": [ > { > "provider": "jumpcloud", > "purpose": "sso", > "clientId": { > "env": "JUMPCLOUD_IDENTITY_PROVIDER_CLIENT_ID" > }, > "clientSecret": { > "env": "JUMPCLOUD_IDENTITY_PROVIDER_CLIENT_SECRET" > }, > "issuer": { > "env": "JUMPCLOUD_IDENTITY_PROVIDER_ISSUER" > } > } > ] > } > ``` ### Idira [Idira custom OpenID Connect application documentation](https://docs.cyberark.com/manage/latest/en/content/identity/applications/appscustom/openidaddconfigapp.htm) An Idira connection can be used for [authentication](/docs/configuration/auth/authentication). Sourcebot uses Idira's OpenID Connect support to authenticate users. > **instructions** > > **1. Create an OpenID Connect application in Idira** > > In the Idira Admin Portal, go to **Manage > Identities > Web apps**, add the custom **OpenID Connect** application, and configure its Trust settings. > > When configuring the application: > > * Add `/api/auth/callback/idira` to the **Authorized Redirect URIs** (ex. [https://sourcebot.coolcorp.com/api/auth/callback/idira](https://sourcebot.coolcorp.com/api/auth/callback/idira)) > * Keep exact redirect URI matching enabled > * Grant the users, groups, or roles that should be able to sign in permission to run the application > > From the application's Trust page, note the `CLIENT_ID` and `ISSUER`. Generate a client secret and store it securely. Idira displays the secret only until you confirm that you have saved it. > > **2. Define environment variables** > > Provide the client id, secret, and issuer URL to Sourcebot using environment variables. These variables can be named whatever you like > (ex. `IDIRA_IDENTITY_PROVIDER_CLIENT_ID`, `IDIRA_IDENTITY_PROVIDER_CLIENT_SECRET`, and `IDIRA_IDENTITY_PROVIDER_ISSUER`). > > **3. Define the identity provider config** > > Add the Idira provider to the `identityProviders` object in the [config file](/docs/configuration/config-file): > > ```json wrap icon="code" theme={null} > { > "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", > "identityProviders": { > "idira": { > "provider": "idira", > "purpose": "sso", > "clientId": { > "env": "IDIRA_IDENTITY_PROVIDER_CLIENT_ID" > }, > "clientSecret": { > "env": "IDIRA_IDENTITY_PROVIDER_CLIENT_SECRET" > }, > "issuer": { > "env": "IDIRA_IDENTITY_PROVIDER_ISSUER" > } > } > } > } > ``` > > If you use a custom identity provider id instead of `idira`, use that id in the callback URL as described in [multiple identity providers](#configuring-multiple-providers-of-the-same-type). ### Google Cloud IAP [Google Cloud IAP Documentation](https://cloud.google.com/iap/docs) Google Cloud Identity-Aware Proxy (IAP) can be used for [authentication](/docs/configuration/auth/authentication). IAP provides a layer of security for applications deployed on Google Cloud, allowing you to control access based on user identity and context. > [!NOTE] > > GCP IAP works differently from other identity providers. Instead of redirecting users to an OAuth flow, IAP intercepts requests at the infrastructure level and adds a signed JWT header that Sourcebot validates. This means users are automatically authenticated when accessing Sourcebot through an IAP-protected endpoint. > **instructions** > > **1. Enable IAP for your application** > > Your Sourcebot deployment must be behind Google Cloud IAP. Follow [this guide](https://cloud.google.com/iap/docs/enabling-on-premises-howto) by Google to enable IAP for your application. > > After enabling IAP, note the **Signed Header JWT Audience**. You can find this in the Google Cloud Console under **Security → Identity-Aware Proxy → (your application) → Edit OAuth Client → Application settings**. > > The audience will be in the format: `/projects//global/backendServices/` or `/projects//apps/`. > > **2. Define environment variables** > > Set the IAP audience as an environment variable. This can be named whatever you like (ex. `GCP_IAP_AUDIENCE`). > > **3. Define the identity provider config** > > Create a `identityProvider` object in the [config file](/docs/configuration/config-file) with the following fields: > > ```json wrap icon="code" theme={null} > { > "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", > "identityProviders": [ > { > "provider": "gcp-iap", > "purpose": "sso", > "audience": { > "env": "GCP_IAP_AUDIENCE" > } > } > ] > } > ``` # Account linking You can connect GitHub, GitLab, Bitbucket Cloud, or Bitbucket Data Center accounts for [permission syncing](/docs/features/permission-syncing) without using those accounts to sign in to Sourcebot. Follow the provider's setup instructions above, then set `purpose` to `"account_linking"`. Set `accountLinkingRequired` to `true` if users must connect an account after signing in, or `false` to make linking optional. ```json wrap icon="code" GitHub account linking for permission syncing theme={null} { "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", "identityProviders": [ { "provider": "github", "purpose": "account_linking", "accountLinkingRequired": true, "clientId": { "env": "GITHUB_IDENTITY_PROVIDER_CLIENT_ID" }, "clientSecret": { "env": "GITHUB_IDENTITY_PROVIDER_CLIENT_SECRET" } } ] } ``` Providers with `purpose: "sso"` can also supply the linked account used for permission syncing. See [Permission syncing](/docs/features/permission-syncing) for provider-specific setup requirements. # Configuring multiple providers of the same type By default, each provider in the `identityProviders` array is identified by an **id** equal to its `provider` value. This id determines the provider's OAuth **callback URL** (sometimes called the redirect URL): ``` /api/auth/callback/ ``` This is why the examples above register callback URLs like `/api/auth/callback/github`. The array form supports only **one instance per provider type**. To configure **multiple instances of the same provider type** (for example, gitlab.com alongside a self-hosted GitLab instance), switch `identityProviders` to its object form, where you assign each provider a unique id: ```json wrap icon="code" Two GitLab providers, one for gitlab.com and one for a self-hosted instance theme={null} { "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", "identityProviders": { "gitlab-cloud": { "provider": "gitlab", "purpose": "sso", "displayName": "GitLab.com", "clientId": { "env": "GITLAB_CLOUD_CLIENT_ID" }, "clientSecret": { "env": "GITLAB_CLOUD_CLIENT_SECRET" } }, "gitlab-selfhosted": { "provider": "gitlab", "purpose": "sso", "displayName": "Selfhosted GitLab", "baseUrl": "https://gitlab.example.com", "clientId": { "env": "GITLAB_SELFHOSTED_CLIENT_ID" }, "clientSecret": { "env": "GITLAB_SELFHOSTED_CLIENT_SECRET" } } } } ``` Each provider keeps the same fields documented above. The only differences are: * `identityProviders` is an **object** keyed by id instead of an array. * The id you choose (`gitlab-cloud`, `gitlab-selfhosted`) sets the callback URL, so you register `/api/auth/callback/gitlab-cloud` and `/api/auth/callback/gitlab-selfhosted` with their respective OAuth clients. * Set an optional `displayName` on each provider to give it a distinct label on the login screen. Without it, both instances fall back to the same provider-type name (for example, "GitLab"), making them hard to tell apart. > [!NOTE] > > Each instance needs its own OAuth client (its own `clientId` and `clientSecret`) registered with the matching callback URL. # Config File Source: https://docs.sourcebot.dev/docs/configuration/config-file 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: ```bash icon="terminal" Passing in a CONFIG_PATH to Sourcebot theme={null} docker run \ -v $(pwd)/config.json:/data/config.json \ -e CONFIG_PATH=/data/config.json \ ... \ # other options docker.sourcebot.dev/sourcebot-dev/sourcebot:latest ``` The config file tells Sourcebot which repos to index, what language models to use, and various other settings as defined in the [schema](#config-file-schema). # Config File Schema The config file you provide Sourcebot must follow the [schema](https://github.com/sourcebot-dev/sourcebot/blob/main/schemas/v3/index.json). This schema consists of the following properties: * [Connections](/docs/connections/indexing-your-code) (`connections`): Defines a set of connections that tell Sourcebot which repos to index and from where * [Language Models](/docs/configuration/language-model-providers) (`models`): Defines a set of language model providers for use with [Ask Sourcebot](/docs/features/ask) * [Settings](#settings) (`settings`): Additional settings to tweak your Sourcebot deployment * [Search Contexts](/docs/features/search/search-contexts) (`contexts`): Groupings of repos that you can search against # Config File Syncing Sourcebot syncs the config file on startup, and automatically whenever a change is detected. # Settings The following are settings that can be provided in your config file to modify Sourcebot's behavior | Setting | Type | Default | Minimum | Description / Notes | | - | - | - | - | - | | `maxFileSize` | number | 2 MB | 1 | Maximum size (bytes) of a file to index. Files exceeding this are skipped. | | `maxTrigramCount` | number | 20 000 | 1 | Maximum trigrams per document. Larger files are skipped. | | `reindexIntervalMs` | number | 1 hour | 1 | Interval at which all repositories are re‑indexed. | | `resyncConnectionIntervalMs` | number | 24 hours | 1 | Interval for checking connections that need re‑syncing. | | `resyncConnectionPollingIntervalMs` | number | 1 second | 1 | DB polling rate for connections that need re‑syncing. | | `reindexRepoPollingIntervalMs` | number | 1 second | 1 | DB polling rate for repos that should be re‑indexed. | | `maxConnectionSyncJobConcurrency` | number | 8 | 1 | Concurrent connection‑sync jobs. | | `maxRepoIndexingJobConcurrency` | number | 8 | 1 | Concurrent repo‑indexing jobs. | | `maxRepoGarbageCollectionJobConcurrency` | number | 8 | 1 | Concurrent repo‑garbage‑collection jobs. | | `repoGarbageCollectionGracePeriodMs` | number | 10 seconds | 1 | Grace period to avoid deleting shards while loading. | | `repoIndexTimeoutMs` | number | 2 hours | 1 | Timeout for a single repo‑indexing run. | | `repoDrivenPermissionSyncIntervalMs` | number | 24 hours | 1 | Interval at which the repo permission syncer should run. | | `userDrivenPermissionSyncIntervalMs` | number | 24 hours | 1 | Interval at which the user permission syncer should run. | | `experiment_repoDrivenPermissionSyncIntervalMs` **(deprecated)** | number | 24 hours | 1 | Use `repoDrivenPermissionSyncIntervalMs` instead. | | `experiment_userDrivenPermissionSyncIntervalMs` **(deprecated)** | number | 24 hours | 1 | Use `userDrivenPermissionSyncIntervalMs` instead. | | `maxAccountPermissionSyncJobConcurrency` | number | 8 | 1 | Concurrent account permission sync jobs. | | `maxRepoPermissionSyncJobConcurrency` | number | 8 | 1 | Concurrent repo permission sync jobs. | # 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: > **Environment Variables** > > ```json theme={null} > { > "token": { > "env": "TOKEN_NAME" > } > } > ``` > **Google Cloud Secrets** > > ```json theme={null} > { > "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. > **Token** > > ```jsonc theme={null} > { > "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" > } > } > }, > } > ``` > **String** > > ```jsonc theme={null} > { > "environmentOverrides": { > "EMAIL_FROM_ADDRESS": { > "type": "string", > "value": "hello@sourcebot.dev" > } > } > } > ``` > **Number** > > ```jsonc theme={null} > { > "environmentOverrides": { > "SOURCEBOT_CHAT_MODEL_TEMPERATURE": { > "type": "number", > "value": 0.5 > } > } > } > ``` > **Boolean** > > ```jsonc theme={null} > { > "environmentOverrides": { > "PERMISSION_SYNC_ENABLED": { > "type": "boolean", > "value": true > } > } > } > ``` **Note:** Overrides are **not** set as system environment variables, and instead are resolved at runtime on startup and stored in memory. > **Schema reference** > > [schemas/v3/environmentOverrides.json](https://github.com/sourcebot-dev/sourcebot/blob/main/schemas/v3/environmentOverrides.json) > > ```json theme={null} > { > "type": "object", > "description": "Environment variable overrides.", > "title": "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 > } > ] > } > } > } > ``` # Environment variables Source: https://docs.sourcebot.dev/docs/configuration/environment-variables > [!NOTE] > > 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 guides](/docs/deployment/docker-compose) instead. ### Core Environment Variables The following environment variables allow you to configure your Sourcebot deployment. | Variable | Default | Description | | :- | :- | :- | | `AUTH_SECRET` **(required)** | - | Used to validate login session cookies. Genearte one with `openssl rand -base64 33`. | | `AUTH_SESSION_MAX_AGE_SECONDS` | `2592000` (30 days) | Relative time from now in seconds when to expire the session. | | `AUTH_SESSION_UPDATE_AGE_SECONDS` | `86400` (1 day) | How often the session should be updated in seconds. If set to `0`, session is updated every time. | | `OAUTH_AUTHORIZATION_CODE_TTL_SECONDS` | `600` (10 minutes) | Lifetime of an OAuth authorization code, in seconds. | | `OAUTH_ACCESS_TOKEN_TTL_SECONDS` | `3600` (1 hour) | Lifetime of an OAuth access token, in seconds. | | `OAUTH_REFRESH_TOKEN_TTL_SECONDS` | `7776000` (90 days) | Lifetime of an OAuth refresh token, in seconds. | | `AUTH_URL` | - | URL of your Sourcebot deployment, e.g., `https://example.com` or `http://localhost:3000`. | | `SOURCEBOT_ONBOARDING_COMPLETION_URL` | `https://www.sourcebot.dev/onboard_complete` | Website opened after successful onboarding. Set an HTTP(S) URL to test against a local website. | | `CONFIG_PATH` | `-` | The container relative path to the declarative configuration file. See [this doc](/docs/configuration/declarative-config) for more info. | | `DATA_CACHE_DIR` | `$DATA_DIR/.sourcebot` | The root data directory in which all data written to disk by Sourcebot will be located. | | `DATA_DIR` | `/data` | The directory within the container to store all persistent data. Typically, this directory will be volume mapped such that data is persisted across container restarts (e.g., `docker run -v $(pwd):/data`) | | `DATABASE_URL` **(required)** | - | Connection string of your Postgres database, e.g. `postgresql://user:password@host:5432/sourcebot`.If you'd like to use a non-default schema, you can provide it as a parameter in the database url.You can also use `DATABASE_HOST`, `DATABASE_USERNAME`, `DATABASE_PASSWORD`, `DATABASE_NAME`, and `DATABASE_ARGS` to construct the database url. | | `EMAIL_FROM_ADDRESS` | `-` | The email address that transactional emails will be sent from. See [this doc](/docs/configuration/transactional-emails) for more info. | | `REDIS_URL` **(required)** | - | Connection string of your Redis instance, e.g. `redis://host:6379`.To enable TLS, see [this doc](/docs/deployment/infrastructure/redis#tls). | | `REDIS_REMOVE_ON_COMPLETE` | `0` | Controls how many completed jobs are allowed to remain in Redis queues | | `REDIS_REMOVE_ON_FAIL` | `100` | Controls how many failed jobs are allowed to remain in Redis queues | | `REPO_SYNC_RETRY_BASE_SLEEP_SECONDS` | `60` | The base sleep duration (in seconds) for exponential backoff when retrying repository sync operations that fail | | `GITLAB_CLIENT_QUERY_TIMEOUT_SECONDS` | `600` | The timeout duration (in seconds) for GitLab client queries | | `SMTP_CONNECTION_URL` | `-` | The url to the SMTP service used for sending transactional emails. See [this doc](/docs/configuration/transactional-emails) for more info.You can also use `SMTP_HOST`, `SMTP_PORT`, `SMTP_USERNAME`, and `SMTP_PASSWORD` to construct the SMTP connection url. | | `SMTP_HOST` | `-` | The hostname of the SMTP server. Used to construct `SMTP_CONNECTION_URL` when individual SMTP variables are provided. | | `SMTP_PORT` | `-` | The port of the SMTP server. | | `SMTP_USERNAME` | `-` | The username for SMTP authentication. | | `SMTP_PASSWORD` | `-` | The password for SMTP authentication. | | `SOURCEBOT_ENCRYPTION_KEY` **(required)** | - | Used to encrypt connection secrets and generate API keys. Generate one with `openssl rand -base64 24`. | | `SOURCEBOT_PUBLIC_KEY_PATH` | `/app/public.pem` | Sourcebot's public key that's used to verify encrypted license key signatures. | | `SOURCEBOT_LOG_LEVEL` | `info` | The Sourcebot logging level. Valid values are `debug`, `info`, `warn`, `error`, in order of severity. | | `SOURCEBOT_STRUCTURED_LOGGING_ENABLED` | `false` | Enables/disable structured JSON logging. See [this doc](/docs/configuration/structured-logging) for more info. | | `SOURCEBOT_STRUCTURED_LOGGING_FILE` | - | Optional file to log to if structured logging is enabled | | `DEFAULT_MAX_MATCH_COUNT` | `10000` | The default maximum number of search results to return when using search in the web app. | | `DEFAULT_HOME_VIEW_PAGE` | `search` | Sets the default home page when no user home page preference is set. Use `ask` to default to Ask Sourcebot or `search` to default to Code Search. | | `ALWAYS_INDEX_FILE_PATTERNS` | - | A comma separated list of glob patterns matching file paths that should always be indexed, regardless of size or number of trigrams. | | `SOURCEBOT_CHAT_ATTACHMENT_MAX_IMAGE_BYTES` | `10485760` (10 MiB) | Maximum size in bytes of a single image attachment uploaded to Ask Sourcebot. Enforced server-side at upload time. | | `SOURCEBOT_CHAT_ATTACHMENT_ORPHAN_TTL_HOURS` | `24` | How long in hours an uploaded-but-unsent attachment is retained before being deleted by the orphan sweep. Set to `0` to disable the sweep. | | `SOURCEBOT_LLM_USER_EMAIL_HEADER_ENABLED` | `false` | When enabled, Sourcebot sends the authenticated user's lower-cased email address to configured language model providers in the `X-Sourcebot-User-Email` request header. | | `NODE_USE_ENV_PROXY` | `0` | Enables Node.js to automatically use `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables for network requests. Set to `1` to enable or `0` to disable. See [this doc](https://nodejs.org/en/learn/http/enterprise-network-configuration) for more info. | | `HTTP_PROXY` | - | HTTP proxy URL for routing non-SSL requests through a proxy server (e.g., `http://proxy.company.com:8080`). Requires `NODE_USE_ENV_PROXY=1`. | | `HTTPS_PROXY` | - | HTTPS proxy URL for routing SSL requests through a proxy server (e.g., `http://proxy.company.com:8080`). Requires `NODE_USE_ENV_PROXY=1`. | | `NO_PROXY` | - | Comma-separated list of hostnames or domains that should bypass the proxy (e.g., `localhost,127.0.0.1,.internal.domain`). Requires `NODE_USE_ENV_PROXY=1`. | | `SOURCEBOT_EE_AUDIT_RETENTION_DAYS` | `180` | The number of days to retain audit logs. Audit log records older than this will be automatically pruned daily. Set to `0` to disable pruning and retain logs indefinitely. | | `AUTH_EE_GCP_IAP_ENABLED` | `false` | When enabled, allows Sourcebot to automatically register/login from a successful GCP IAP redirect | | `AUTH_EE_GCP_IAP_AUDIENCE` | - | The GCP IAP audience to use when verifying JWT tokens. Must be set to enable GCP IAP JIT provisioning | | `PERMISSION_SYNC_ENABLED` | `false` | Enables [permission syncing](/docs/features/permission-syncing). | | `PERMISSION_SYNC_REPO_DRIVEN_ENABLED` | `true` | Enables/disables [repo-driven permission syncing](/docs/features/permission-syncing#how-it-works). Only applies when `PERMISSION_SYNC_ENABLED` is `true`. | | `AUTH_EE_ALLOW_EMAIL_ACCOUNT_LINKING` | `true` | When enabled, different SSO accounts with the same email address will automatically be linked. | | `DISABLE_API_KEY_CREATION_FOR_NON_OWNER_USERS` | `false` | When enabled, only organization owners can create API keys. Non-owner members will receive a `403` error if they attempt to create one. | | `DISABLE_API_KEY_USAGE_FOR_NON_OWNER_USERS` | `false` | When enabled, only organization owners can create or use API keys. Non-owner members will receive a `403` error if they attempt to create or authenticate with an API key. If you only want to restrict creation (not usage), use `DISABLE_API_KEY_CREATION_FOR_NON_OWNER_USERS` instead. | ### Review Agent Environment Variables | Variable | Default | Description | | :- | :- | :- | | `GITHUB_REVIEW_AGENT_APP_ID` | `-` | The GitHub App ID used for review agent authentication. | | `GITHUB_REVIEW_AGENT_APP_PRIVATE_KEY_PATH` | `-` | The container relative path to the private key file for the GitHub App used by the review agent. | | `GITHUB_REVIEW_AGENT_APP_WEBHOOK_SECRET` | `-` | The webhook secret for the GitHub App used by the review agent. | | `OPENAI_API_KEY` | `-` | The OpenAI API key used by the review agent. | | `REVIEW_AGENT_API_KEY` | `-` | The Sourcebot API key used by the review agent. | | `REVIEW_AGENT_AUTO_REVIEW_ENABLED` | `false` | Enables/disables automatic code reviews by the review agent. | | `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. # Language Model Providers Source: https://docs.sourcebot.dev/docs/configuration/language-model-providers > [!NOTE] > > Looking to self-host your own model? Check out the [OpenAI Compatible](#openai-compatible) provider. To use [Ask Sourcebot](/docs/features/ask) you must define at least one Language Model Provider. These providers are defined within the [config file](/docs/configuration/config-file) you provide Sourcebot. ```json wrap icon="code" Example config with language model provider theme={null} { "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", "models": [ // 1. Google Vertex config for Gemini 2.5 Pro { "provider": "google-vertex", "model": "gemini-2.5-pro", "displayName": "Gemini 2.5 Pro", "project": "sourcebot", "credentials": { "env": "GOOGLE_APPLICATION_CREDENTIALS" } }, // 2. OpenAI config for o3 { "provider": "openai", "model": "o3", "displayName": "o3", "token": { "env": "OPENAI_API_KEY" } } ] } ``` # Supported Providers Sourcebot uses the [Vercel AI SDK](https://ai-sdk.dev/docs/introduction), so it can integrate with any provider the SDK supports. If you don't see your provider below please submit a [feature request](https://github.com/sourcebot-dev/sourcebot/issues/new?template=feature_request.md). For a detailed description of all the providers, please refer to the [schema](https://github.com/sourcebot-dev/sourcebot/blob/main/schemas/v3/languageModel.json). > [!NOTE] > > Any parameter defined using `env` will read the value from the corresponding environment variable you provide Sourcebot ### Amazon Bedrock [Vercel AI SDK Amazon Bedrock Docs](https://ai-sdk.dev/providers/ai-sdk-providers/amazon-bedrock) ```json wrap icon="code" Example config with Amazon Bedrock provider theme={null} { "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", "models": [ { "provider": "amazon-bedrock", "model": "YOUR_MODEL_HERE", "displayName": "OPTIONAL_DISPLAY_NAME", "accessKeyId": { "env": "AWS_ACCESS_KEY_ID" }, "accessKeySecret": { "env": "AWS_SECRET_ACCESS_KEY" }, "sessionToken": { "env": "AWS_SESSION_TOKEN" }, "region": "YOUR_REGION_HERE", // defaults to the AWS_REGION env var if not set "baseUrl": "OPTIONAL_BASE_URL", "maxOutputTokens": 32000 // optional, see below } ] } ``` Sourcebot recognizes Claude models by their Bedrock model ID, including cross-region inference profiles such as `us.anthropic.claude-opus-4-7`. For these models: * Claude 4.6 and later run with adaptive thinking. Claude 3.7 Sonnet and earlier Claude 4 models use a thinking budget of `ANTHROPIC_THINKING_BUDGET_TOKENS`, taken out of the output limit. * Sourcebot does not send a configured `temperature` while thinking is on, because Claude does not accept it. * Each request allows the model's full output limit (for example, 64,000 tokens for Claude Sonnet 4.6 and 128,000 tokens for Claude Opus 4.6). Without it, Bedrock caps Claude responses at 4,096 tokens. Set `maxOutputTokens` to change the output limit: * **Application inference profiles.** Their IDs do not name the model, so Sourcebot cannot look up its limit. Set `maxOutputTokens` to avoid truncated responses. * **Throttling.** Bedrock reserves `maxOutputTokens` against your tokens-per-minute quota when each request starts, and counts each Claude output token five times. With a small quota, a single request can exceed it. If requests are throttled, lower `maxOutputTokens` or [request a higher quota](https://docs.aws.amazon.com/bedrock/latest/userguide/quotas-token-burndown.html). ### Anthropic [Vercel AI SDK Anthropic Docs](https://ai-sdk.dev/providers/ai-sdk-providers/anthropic) ```json wrap icon="code" Example config with Anthropic provider theme={null} { "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", "models": [ { "provider": "anthropic", "model": "YOUR_MODEL_HERE", "displayName": "OPTIONAL_DISPLAY_NAME", // Auth can be provided via a API key that is sent using the `x-api-key` header... "token": { "env": "ANTHROPIC_API_KEY" }, // ...or via a auth token sent using the `Authorization: Bearer` header. "authToken": { "env": "ANTHROPIC_AUTH_TOKEN" }, "baseUrl": "OPTIONAL_BASE_URL" } ] } ``` ### Azure OpenAI [Vercel AI SDK Azure OpenAI Docs](https://ai-sdk.dev/providers/ai-sdk-providers/azure) The `model` field should be set to your Azure OpenAI deployment name. Either `resourceName` or `baseUrl` must be set. The `resourceName` is used to construct the URL `https://{resourceName}.openai.azure.com/openai/v1{path}`. If `baseUrl` is provided, `resourceName` is ignored. The `reasoningSummary` field controls whether the model returns its reasoning process. Set to `auto` for a condensed summary, `detailed` for more comprehensive reasoning, or `none` to disable. Defaults to `auto`. ```json wrap icon="code" Example config with Azure AI provider theme={null} { "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", "models": [ { "provider": "azure", "model": "YOUR_DEPLOYMENT_NAME", "displayName": "OPTIONAL_DISPLAY_NAME", "resourceName": "YOUR_RESOURCE_NAME", // defaults to the AZURE_RESOURCE_NAME env var if not set "apiVersion": "OPTIONAL_API_VERSION", "token": { "env": "AZURE_API_KEY" }, "baseUrl": "OPTIONAL_BASE_URL", // use instead of resourceName for custom endpoints "reasoningEffort": "OPTIONAL_REASONING_EFFORT", // defaults to "medium" "reasoningSummary": "auto" // "auto" | "detailed" | "none". Defaults to "auto" } ] } ``` ### Deepseek [Vercel AI SDK Deepseek Docs](https://ai-sdk.dev/providers/ai-sdk-providers/deepseek) ```json wrap icon="code" Example config with Deepseek provider theme={null} { "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", "models": [ { "provider": "deepseek", "model": "YOUR_MODEL_HERE", "displayName": "OPTIONAL_DISPLAY_NAME", "token": { "env": "DEEPSEEK_API_KEY" }, "baseUrl": "OPTIONAL_BASE_URL" } ] } ``` ### Google Generative AI [Vercel AI SDK Google Generative AI Docs](https://ai-sdk.dev/providers/ai-sdk-providers/google-generative-ai) The `thinkingLevel` field controls the depth of reasoning for Gemini 3 models. Valid values are `minimal`, `low`, `medium`, and `high`. See [thinking levels](https://ai.google.dev/gemini-api/docs/thinking#thinking-levels). The `thinkingBudget` field sets the number of thinking tokens for Gemini 2.5 models. Set to `-1` for dynamic thinking. See [thinking budget](https://ai.google.dev/gemini-api/docs/thinking#set-budget). ```json wrap icon="code" Example config with Google Generative AI provider theme={null} { "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", "models": [ { "provider": "google-generative-ai", "model": "YOUR_MODEL_HERE", "displayName": "OPTIONAL_DISPLAY_NAME", "token": { "env": "GOOGLE_GENERATIVE_AI_API_KEY" }, "baseUrl": "OPTIONAL_BASE_URL", "thinkingLevel": "high", // "minimal" | "low" | "medium" | "high" (Gemini 3 models) "thinkingBudget": -1 // number of thinking tokens, -1 for dynamic (Gemini 2.5 models) } ] } ``` ### Google Vertex > [!NOTE] > > If you're using an Anthropic model on Google Vertex, you must define a [Google Vertex Anthropic](#google-vertex-anthropic) provider instead > [!NOTE] > > The `credentials` parameter here expects a **path** to a [credentials](https://console.cloud.google.com/apis/credentials) file. This file **must be in a volume mounted by Sourcebot** for it to be readable. [Vercel AI SDK Google Vertex AI Docs](https://ai-sdk.dev/providers/ai-sdk-providers/google-vertex) The `thinkingLevel` field controls the depth of reasoning for Gemini 3 models. Valid values are `minimal`, `low`, `medium`, and `high`. See [thinking levels](https://ai.google.dev/gemini-api/docs/thinking#thinking-levels). The `thinkingBudget` field sets the number of thinking tokens for Gemini 2.5 models. Set to `-1` for dynamic thinking. See [thinking budget](https://ai.google.dev/gemini-api/docs/thinking#set-budget). ```json wrap icon="code" Example config with Google Vertex provider theme={null} { "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", "models": [ { "provider": "google-vertex", "model": "YOUR_MODEL_HERE", "displayName": "OPTIONAL_DISPLAY_NAME", "project": "YOUR_PROJECT_ID", // defaults to the GOOGLE_VERTEX_PROJECT env var if not set "region": "YOUR_REGION_HERE", // defaults to the GOOGLE_VERTEX_REGION env var if not set "credentials": { "env": "GOOGLE_APPLICATION_CREDENTIALS" }, "baseUrl": "OPTIONAL_BASE_URL", "thinkingLevel": "high", // "minimal" | "low" | "medium" | "high" (Gemini 3 models) "thinkingBudget": -1 // number of thinking tokens, -1 for dynamic (Gemini 2.5 models) } ] } ``` ### Google Vertex Anthropic > [!NOTE] > > The `credentials` parameter here expects a **path** to a [credentials](https://console.cloud.google.com/apis/credentials) file. This file **must be in a volume mounted by Sourcebot** for it to be readable. [Vercel AI SDK Google Vertex Anthropic Docs](https://ai-sdk.dev/providers/ai-sdk-providers/google-vertex#google-vertex-anthropic-provider-usage) ```json wrap icon="code" Example config with Google Vertex Anthropic provider theme={null} { "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", "models": [ { "provider": "google-vertex-anthropic", "model": "YOUR_MODEL_HERE", "displayName": "OPTIONAL_DISPLAY_NAME", "project": "YOUR_PROJECT_ID", // defaults to the GOOGLE_VERTEX_PROJECT env var if not set "region": "YOUR_REGION_HERE", // defaults to the GOOGLE_VERTEX_REGION env var if not set "credentials": { "env": "GOOGLE_APPLICATION_CREDENTIALS" }, "baseUrl": "OPTIONAL_BASE_URL" } ] } ``` ### Mistral [Vercel AI SDK Mistral Docs](https://ai-sdk.dev/providers/ai-sdk-providers/mistral) ```json wrap icon="code" Example config with Mistral provider theme={null} { "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", "models": [ { "provider": "mistral", "model": "YOUR_MODEL_HERE", "displayName": "OPTIONAL_DISPLAY_NAME", "token": { "env": "MISTRAL_API_KEY" }, "baseUrl": "OPTIONAL_BASE_URL" } ] } ``` ### OpenAI [Vercel AI SDK OpenAI Docs](https://ai-sdk.dev/providers/ai-sdk-providers/openai) The `reasoningSummary` field controls whether the model returns its reasoning process. Set to `auto` for a condensed summary, `detailed` for more comprehensive reasoning, or `none` to disable. Defaults to `auto`. ```json wrap icon="code" Example config with OpenAI provider theme={null} { "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", "models": [ { "provider": "openai", "model": "YOUR_MODEL_HERE", "displayName": "OPTIONAL_DISPLAY_NAME", "token": { "env": "OPENAI_API_KEY" }, "baseUrl": "OPTIONAL_BASE_URL", "reasoningEffort": "OPTIONAL_REASONING_EFFORT", // defaults to "medium" "reasoningSummary": "auto" // "auto" | "detailed" | "none". Defaults to "auto" } ] } ``` ### OpenAI Compatible [Vercel AI SDK OpenAI Compatible Docs](https://ai-sdk.dev/providers/openai-compatible-providers) The OpenAI compatible provider allows you to use any model that is compatible with the OpenAI [Chat Completions API](https://github.com/ollama/ollama/blob/main/docs/openai.md). This includes self-hosted tools like [Ollama](https://ollama.ai/) and [llama.cpp](https://github.com/ggerganov/llama.cpp). ```json wrap icon="code" Example config with OpenAI Compatible provider theme={null} { "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", "models": [ { "provider": "openai-compatible", "baseUrl": "BASE_URL_HERE", "model": "YOUR_MODEL_HERE", "displayName": "OPTIONAL_DISPLAY_NAME", "token": { "env": "OPTIONAL_API_KEY" }, // Optional query parameters can be passed in the request url as: "queryParams": { // raw string values "optional-query-param": "foo", // or as environment variables "optional-query-param-secret": { "env": "MY_SECRET_ENV_VAR" } } } ] } ``` > **Troubleshooting** > > * When using [llama.cpp](https://github.com/ggml-org/llama.cpp), if you hit "Failed after 3 attempts. Last error: tools param requires --jinja flag", add the `--jinja` flag to your `llama-server` command. > * If you're seeing the LLM outputing reasoning tokens wrapped in XML tags (e.g., ``, ``, etc.), you can configure the `reasoningTag` parameter to the name of the tag (without angle brackets). This parameter defaults to `think`. ### OpenRouter [Vercel AI SDK OpenRouter Docs](https://ai-sdk.dev/providers/community-providers/openrouter) ```json wrap icon="code" Example config with OpenRouter provider theme={null} { "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", "models": [ { "provider": "openrouter", "model": "YOUR_MODEL_HERE", "displayName": "OPTIONAL_DISPLAY_NAME", "token": { "env": "OPENROUTER_API_KEY" }, "baseUrl": "OPTIONAL_BASE_URL" } ] } ``` ### xAI [Vercel AI SDK xAI Docs](https://ai-sdk.dev/providers/ai-sdk-providers/xai) ```json wrap icon="code" Example config with xAI provider theme={null} { "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", "models": [ { "provider": "xai", "model": "YOUR_MODEL_HERE", "displayName": "OPTIONAL_DISPLAY_NAME", "token": { "env": "XAI_API_KEY" }, "baseUrl": "OPTIONAL_BASE_URL" } ] } ``` # Custom headers You can pass custom headers to the language model provider by using the `headers` parameter. Header values can either be a string or a environment variable. Headers are supported for all providers. ```json wrap icon="code" Example config with custom headers theme={null} { "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", "models": [ { // ... provider, model, displayName, etc... // Key-value pairs of headers "headers": { // Header values can be passed as a environment variable... "my-secret-header": { "env": "MY_SECRET_HEADER_ENV_VAR" }, // ... or directly as a string. "my-non-secret-header": "plaintextvalue" } } ] } ``` # Schema reference > **Reference** > > [schemas/v3/languageModel.json](https://github.com/sourcebot-dev/sourcebot/blob/main/schemas/v3/languageModel.json) > > ```json theme={null} > { > "type": "object", > "title": "LanguageModel", > "definitions": { > "AmazonBedrockLanguageModel": { > "type": "object", > "properties": { > "provider": { > "const": "amazon-bedrock", > "description": "Amazon Bedrock Configuration" > }, > "model": { > "type": "string", > "description": "The name of the language model." > }, > "displayName": { > "type": "string", > "description": "Optional display name." > }, > "accessKeyId": { > "description": "Optional access key ID to use with the model. Defaults to the `AWS_ACCESS_KEY_ID` environment variable.", > "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 > } > ] > }, > "accessKeySecret": { > "description": "Optional secret access key to use with the model. Defaults to the `AWS_SECRET_ACCESS_KEY` environment variable.", > "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 > } > ] > }, > "sessionToken": { > "description": "Optional session token to use with the model. Defaults to the `AWS_SESSION_TOKEN` environment variable.", > "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 > } > ] > }, > "region": { > "type": "string", > "description": "The AWS region. Defaults to the `AWS_REGION` environment variable.", > "examples": [ > "us-east-1", > "us-west-2", > "eu-west-1" > ] > }, > "baseUrl": { > "type": "string", > "format": "url", > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$", > "description": "Optional base URL." > }, > "temperature": { > "type": "number", > "description": "Optional temperature setting to use with the model." > }, > "maxOutputTokens": { > "type": "integer", > "minimum": 1, > "description": "Optional maximum number of output tokens per request, including thinking. Defaults to the model's output limit for known Claude models, and to Bedrock's own default otherwise. Set this for application inference profiles or other models Sourcebot cannot identify, or lower it if your tokens-per-minute quota throttles requests." > }, > "headers": { > "type": "object", > "description": "Optional headers to use with the model.", > "patternProperties": { > "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$": { > "anyOf": [ > { > "type": "string" > }, > { > "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 > } > ] > } > ] > } > }, > "additionalProperties": false > } > }, > "required": [ > "provider", > "model" > ], > "additionalProperties": false > }, > "AnthropicLanguageModel": { > "type": "object", > "properties": { > "provider": { > "const": "anthropic", > "description": "Anthropic Configuration" > }, > "model": { > "type": "string", > "description": "The name of the language model." > }, > "displayName": { > "type": "string", > "description": "Optional display name." > }, > "token": { > "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 > } > ], > "description": "Optional API key to use with the model, sent as the `x-api-key` header. Defaults to the `ANTHROPIC_API_KEY` environment variable." > }, > "authToken": { > "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 > } > ], > "description": "Optional auth token to use with the model, sent as the `Authorization: Bearer` header. Defaults to the `ANTHROPIC_AUTH_TOKEN` environment variable." > }, > "baseUrl": { > "type": "string", > "format": "url", > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$", > "description": "Optional base URL." > }, > "temperature": { > "type": "number", > "description": "Optional temperature setting to use with the model." > }, > "headers": { > "type": "object", > "description": "Optional headers to use with the model.", > "patternProperties": { > "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$": { > "anyOf": [ > { > "type": "string" > }, > { > "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 > } > ] > } > ] > } > }, > "additionalProperties": false > } > }, > "required": [ > "provider", > "model" > ], > "additionalProperties": false > }, > "AzureLanguageModel": { > "type": "object", > "properties": { > "provider": { > "const": "azure", > "description": "Azure Configuration" > }, > "model": { > "type": "string", > "description": "The deployment name of the Azure model." > }, > "displayName": { > "type": "string", > "description": "Optional display name." > }, > "resourceName": { > "type": "string", > "description": "Azure resource name. Defaults to the `AZURE_RESOURCE_NAME` environment variable." > }, > "token": { > "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 > } > ], > "description": "Optional API key to use with the model. Defaults to the `AZURE_API_KEY` environment variable." > }, > "apiVersion": { > "type": "string", > "description": "Sets a custom api version. Defaults to `preview`." > }, > "baseUrl": { > "type": "string", > "format": "url", > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$", > "description": "Use a different URL prefix for API calls. Either this or `resourceName` can be used." > }, > "reasoningEffort": { > "type": "string", > "description": "The reasoning effort to use with the model. Defaults to `medium`. See https://platform.openai.com/docs/guides/reasoning#get-started-with-reasonings", > "examples": [ > "none", > "minimal", > "low", > "medium", > "high" > ] > }, > "reasoningSummary": { > "type": "string", > "description": "Controls whether the model returns its reasoning process. Set to 'auto' for a condensed summary, 'detailed' for more comprehensive reasoning, or 'none' to disable. Defaults to 'auto'.", > "examples": [ > "none", > "auto", > "detailed" > ] > }, > "temperature": { > "type": "number", > "description": "Optional temperature setting to use with the model." > }, > "headers": { > "type": "object", > "description": "Optional headers to use with the model.", > "patternProperties": { > "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$": { > "anyOf": [ > { > "type": "string" > }, > { > "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 > } > ] > } > ] > } > }, > "additionalProperties": false > } > }, > "required": [ > "provider", > "model" > ], > "additionalProperties": false > }, > "DeepSeekLanguageModel": { > "type": "object", > "properties": { > "provider": { > "const": "deepseek", > "description": "DeepSeek Configuration" > }, > "model": { > "type": "string", > "description": "The name of the language model." > }, > "displayName": { > "type": "string", > "description": "Optional display name." > }, > "token": { > "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 > } > ], > "description": "Optional API key to use with the model. Defaults to the `DEEPSEEK_API_KEY` environment variable." > }, > "baseUrl": { > "type": "string", > "format": "url", > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$", > "description": "Optional base URL." > }, > "temperature": { > "type": "number", > "description": "Optional temperature setting to use with the model." > }, > "headers": { > "type": "object", > "description": "Optional headers to use with the model.", > "patternProperties": { > "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$": { > "anyOf": [ > { > "type": "string" > }, > { > "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 > } > ] > } > ] > } > }, > "additionalProperties": false > } > }, > "required": [ > "provider", > "model" > ], > "additionalProperties": false > }, > "GoogleGenerativeAILanguageModel": { > "type": "object", > "properties": { > "provider": { > "const": "google-generative-ai", > "description": "Google Generative AI Configuration" > }, > "model": { > "type": "string", > "description": "The name of the language model." > }, > "displayName": { > "type": "string", > "description": "Optional display name." > }, > "token": { > "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 > } > ], > "description": "Optional API key to use with the model. Defaults to the `GOOGLE_GENERATIVE_AI_API_KEY` environment variable." > }, > "baseUrl": { > "type": "string", > "format": "url", > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$", > "description": "Optional base URL." > }, > "thinkingLevel": { > "type": "string", > "description": "Optional thinking level for Gemini 3 models. Controls the depth of reasoning the model performs. See https://ai.google.dev/gemini-api/docs/thinking#thinking-levels", > "enum": [ > "minimal", > "low", > "medium", > "high" > ] > }, > "thinkingBudget": { > "type": "integer", > "description": "Optional thinking budget for Gemini 2.5 models. Sets the number of thinking tokens the model can use when generating a response. Set to -1 for dynamic thinking. See https://ai.google.dev/gemini-api/docs/thinking#set-budget" > }, > "temperature": { > "type": "number", > "description": "Optional temperature setting to use with the model." > }, > "headers": { > "type": "object", > "description": "Optional headers to use with the model.", > "patternProperties": { > "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$": { > "anyOf": [ > { > "type": "string" > }, > { > "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 > } > ] > } > ] > } > }, > "additionalProperties": false > } > }, > "required": [ > "provider", > "model" > ], > "additionalProperties": false > }, > "GoogleVertexAnthropicLanguageModel": { > "type": "object", > "properties": { > "provider": { > "const": "google-vertex-anthropic", > "description": "Google Vertex AI Anthropic Configuration" > }, > "model": { > "type": "string", > "description": "The name of the Anthropic language model running on Google Vertex.", > "examples": [ > "claude-sonnet-4" > ] > }, > "displayName": { > "type": "string", > "description": "Optional display name." > }, > "project": { > "type": "string", > "description": "The Google Cloud project ID. Defaults to the `GOOGLE_VERTEX_PROJECT` environment variable." > }, > "region": { > "type": "string", > "description": "The Google Cloud region. Defaults to the `GOOGLE_VERTEX_REGION` environment variable.", > "examples": [ > "us-central1", > "us-east1", > "europe-west1" > ] > }, > "credentials": { > "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 > } > ], > "description": "Optional file path to service account credentials JSON. Defaults to the `GOOGLE_APPLICATION_CREDENTIALS` environment variable or application default credentials." > }, > "baseUrl": { > "type": "string", > "format": "url", > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$", > "description": "Optional base URL." > }, > "temperature": { > "type": "number", > "description": "Optional temperature setting to use with the model." > }, > "headers": { > "type": "object", > "description": "Optional headers to use with the model.", > "patternProperties": { > "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$": { > "anyOf": [ > { > "type": "string" > }, > { > "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 > } > ] > } > ] > } > }, > "additionalProperties": false > } > }, > "required": [ > "provider", > "model" > ], > "additionalProperties": false > }, > "GoogleVertexLanguageModel": { > "type": "object", > "properties": { > "provider": { > "const": "google-vertex", > "description": "Google Vertex AI Configuration" > }, > "model": { > "type": "string", > "description": "The name of the language model.", > "examples": [ > "gemini-2.0-flash-exp", > "gemini-1.5-pro", > "gemini-1.5-flash" > ] > }, > "displayName": { > "type": "string", > "description": "Optional display name." > }, > "project": { > "type": "string", > "description": "The Google Cloud project ID. Defaults to the `GOOGLE_VERTEX_PROJECT` environment variable." > }, > "region": { > "type": "string", > "description": "The Google Cloud region. Defaults to the `GOOGLE_VERTEX_REGION` environment variable.", > "examples": [ > "us-central1", > "us-east1", > "europe-west1" > ] > }, > "credentials": { > "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 > } > ], > "description": "Optional file path to service account credentials JSON. Defaults to the `GOOGLE_APPLICATION_CREDENTIALS` environment variable or application default credentials." > }, > "baseUrl": { > "type": "string", > "format": "url", > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$", > "description": "Optional base URL." > }, > "thinkingLevel": { > "type": "string", > "description": "Optional thinking level for Gemini 3 models. Controls the depth of reasoning the model performs. See https://ai.google.dev/gemini-api/docs/thinking#thinking-levels", > "enum": [ > "minimal", > "low", > "medium", > "high" > ] > }, > "thinkingBudget": { > "type": "integer", > "description": "Optional thinking budget for Gemini 2.5 models. Sets the number of thinking tokens the model can use when generating a response. Set to -1 for dynamic thinking. See https://ai.google.dev/gemini-api/docs/thinking#set-budget" > }, > "temperature": { > "type": "number", > "description": "Optional temperature setting to use with the model." > }, > "headers": { > "type": "object", > "description": "Optional headers to use with the model.", > "patternProperties": { > "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$": { > "anyOf": [ > { > "type": "string" > }, > { > "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 > } > ] > } > ] > } > }, > "additionalProperties": false > } > }, > "required": [ > "provider", > "model" > ], > "additionalProperties": false > }, > "MistralLanguageModel": { > "type": "object", > "properties": { > "provider": { > "const": "mistral", > "description": "Mistral AI Configuration" > }, > "model": { > "type": "string", > "description": "The name of the language model." > }, > "displayName": { > "type": "string", > "description": "Optional display name." > }, > "token": { > "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 > } > ], > "description": "Optional API key to use with the model. Defaults to the `MISTRAL_API_KEY` environment variable." > }, > "baseUrl": { > "type": "string", > "format": "url", > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$", > "description": "Optional base URL." > }, > "temperature": { > "type": "number", > "description": "Optional temperature setting to use with the model." > }, > "headers": { > "type": "object", > "description": "Optional headers to use with the model.", > "patternProperties": { > "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$": { > "anyOf": [ > { > "type": "string" > }, > { > "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 > } > ] > } > ] > } > }, > "additionalProperties": false > } > }, > "required": [ > "provider", > "model" > ], > "additionalProperties": false > }, > "OpenAILanguageModel": { > "type": "object", > "properties": { > "provider": { > "const": "openai", > "description": "OpenAI Configuration" > }, > "model": { > "type": "string", > "description": "The name of the language model.", > "examples": [ > "gpt-4.1", > "o4-mini", > "o3", > "o3-deep-research" > ] > }, > "displayName": { > "type": "string", > "description": "Optional display name." > }, > "token": { > "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 > } > ], > "description": "Optional API key to use with the model. Defaults to the `OPENAI_API_KEY` environment variable." > }, > "baseUrl": { > "type": "string", > "format": "url", > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$", > "description": "Optional base URL." > }, > "reasoningEffort": { > "type": "string", > "description": "The reasoning effort to use with the model. Defaults to `medium`. See https://platform.openai.com/docs/guides/reasoning#get-started-with-reasonings", > "examples": [ > "none", > "minimal", > "low", > "medium", > "high" > ] > }, > "reasoningSummary": { > "type": "string", > "description": "Controls whether the model returns its reasoning process. Set to 'auto' for a condensed summary, 'detailed' for more comprehensive reasoning, or 'none' to disable. Defaults to 'auto'.", > "examples": [ > "none", > "auto", > "detailed" > ] > }, > "temperature": { > "type": "number", > "description": "Optional temperature setting to use with the model." > }, > "headers": { > "type": "object", > "description": "Optional headers to use with the model.", > "patternProperties": { > "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$": { > "anyOf": [ > { > "type": "string" > }, > { > "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 > } > ] > } > ] > } > }, > "additionalProperties": false > } > }, > "required": [ > "provider", > "model" > ], > "additionalProperties": false > }, > "OpenAICompatibleLanguageModel": { > "type": "object", > "properties": { > "provider": { > "const": "openai-compatible", > "description": "OpenAI Compatible Configuration" > }, > "model": { > "type": "string", > "description": "The name of the language model." > }, > "displayName": { > "type": "string", > "description": "Optional display name." > }, > "token": { > "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 > } > ], > "description": "Optional API key. If specified, adds an `Authorization` header to request headers with the value Bearer ." > }, > "baseUrl": { > "type": "string", > "format": "url", > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$", > "description": "Base URL of the OpenAI-compatible chat completions API endpoint.", > "examples": [ > "http://localhost:8080/v1" > ] > }, > "headers": { > "type": "object", > "description": "Optional headers to use with the model.", > "patternProperties": { > "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$": { > "anyOf": [ > { > "type": "string" > }, > { > "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 > } > ] > } > ] > } > }, > "additionalProperties": false > }, > "queryParams": { > "type": "object", > "description": "Optional query parameters to include in the request url.", > "patternProperties": { > "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$": { > "anyOf": [ > { > "type": "string" > }, > { > "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 > } > ] > } > ] > } > }, > "additionalProperties": false > }, > "reasoningTag": { > "type": "string", > "description": "The name of the XML tag to extract reasoning from (without angle brackets). Defaults to `think`.", > "default": "think", > "examples": [ > "think", > "thinking", > "reasoning" > ] > }, > "temperature": { > "type": "number", > "description": "Optional temperature setting to use with the model." > } > }, > "required": [ > "provider", > "model", > "baseUrl" > ], > "additionalProperties": false > }, > "OpenRouterLanguageModel": { > "type": "object", > "properties": { > "provider": { > "const": "openrouter", > "description": "OpenRouter Configuration" > }, > "model": { > "type": "string", > "description": "The name of the language model." > }, > "displayName": { > "type": "string", > "description": "Optional display name." > }, > "token": { > "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 > } > ], > "description": "Optional API key to use with the model. Defaults to the `OPENROUTER_API_KEY` environment variable." > }, > "baseUrl": { > "type": "string", > "format": "url", > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$", > "description": "Optional base URL." > }, > "temperature": { > "type": "number", > "description": "Optional temperature setting to use with the model." > }, > "headers": { > "type": "object", > "description": "Optional headers to use with the model.", > "patternProperties": { > "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$": { > "anyOf": [ > { > "type": "string" > }, > { > "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 > } > ] > } > ] > } > }, > "additionalProperties": false > } > }, > "required": [ > "provider", > "model" > ], > "additionalProperties": false > }, > "XaiLanguageModel": { > "type": "object", > "properties": { > "provider": { > "const": "xai", > "description": "xAI Configuration" > }, > "model": { > "type": "string", > "description": "The name of the language model.", > "examples": [ > "grok-beta", > "grok-vision-beta" > ] > }, > "displayName": { > "type": "string", > "description": "Optional display name." > }, > "token": { > "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 > } > ], > "description": "Optional API key to use with the model. Defaults to the `XAI_API_KEY` environment variable." > }, > "baseUrl": { > "type": "string", > "format": "url", > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$", > "description": "Optional base URL." > }, > "temperature": { > "type": "number", > "description": "Optional temperature setting to use with the model." > }, > "headers": { > "type": "object", > "description": "Optional headers to use with the model.", > "patternProperties": { > "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$": { > "anyOf": [ > { > "type": "string" > }, > { > "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 > } > ] > } > ] > } > }, > "additionalProperties": false > } > }, > "required": [ > "provider", > "model" > ], > "additionalProperties": false > } > }, > "oneOf": [ > { > "type": "object", > "properties": { > "provider": { > "const": "amazon-bedrock", > "description": "Amazon Bedrock Configuration" > }, > "model": { > "type": "string", > "description": "The name of the language model." > }, > "displayName": { > "type": "string", > "description": "Optional display name." > }, > "accessKeyId": { > "description": "Optional access key ID to use with the model. Defaults to the `AWS_ACCESS_KEY_ID` environment variable.", > "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 > } > ] > }, > "accessKeySecret": { > "description": "Optional secret access key to use with the model. Defaults to the `AWS_SECRET_ACCESS_KEY` environment variable.", > "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 > } > ] > }, > "sessionToken": { > "description": "Optional session token to use with the model. Defaults to the `AWS_SESSION_TOKEN` environment variable.", > "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 > } > ] > }, > "region": { > "type": "string", > "description": "The AWS region. Defaults to the `AWS_REGION` environment variable.", > "examples": [ > "us-east-1", > "us-west-2", > "eu-west-1" > ] > }, > "baseUrl": { > "type": "string", > "format": "url", > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$", > "description": "Optional base URL." > }, > "temperature": { > "type": "number", > "description": "Optional temperature setting to use with the model." > }, > "maxOutputTokens": { > "type": "integer", > "minimum": 1, > "description": "Optional maximum number of output tokens per request, including thinking. Defaults to the model's output limit for known Claude models, and to Bedrock's own default otherwise. Set this for application inference profiles or other models Sourcebot cannot identify, or lower it if your tokens-per-minute quota throttles requests." > }, > "headers": { > "type": "object", > "description": "Optional headers to use with the model.", > "patternProperties": { > "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$": { > "anyOf": [ > { > "type": "string" > }, > { > "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 > } > ] > } > ] > } > }, > "additionalProperties": false > } > }, > "required": [ > "provider", > "model" > ], > "additionalProperties": false > }, > { > "type": "object", > "properties": { > "provider": { > "const": "anthropic", > "description": "Anthropic Configuration" > }, > "model": { > "type": "string", > "description": "The name of the language model." > }, > "displayName": { > "type": "string", > "description": "Optional display name." > }, > "token": { > "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 > } > ], > "description": "Optional API key to use with the model, sent as the `x-api-key` header. Defaults to the `ANTHROPIC_API_KEY` environment variable." > }, > "authToken": { > "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 > } > ], > "description": "Optional auth token to use with the model, sent as the `Authorization: Bearer` header. Defaults to the `ANTHROPIC_AUTH_TOKEN` environment variable." > }, > "baseUrl": { > "type": "string", > "format": "url", > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$", > "description": "Optional base URL." > }, > "temperature": { > "type": "number", > "description": "Optional temperature setting to use with the model." > }, > "headers": { > "type": "object", > "description": "Optional headers to use with the model.", > "patternProperties": { > "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$": { > "anyOf": [ > { > "type": "string" > }, > { > "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 > } > ] > } > ] > } > }, > "additionalProperties": false > } > }, > "required": [ > "provider", > "model" > ], > "additionalProperties": false > }, > { > "type": "object", > "properties": { > "provider": { > "const": "azure", > "description": "Azure Configuration" > }, > "model": { > "type": "string", > "description": "The deployment name of the Azure model." > }, > "displayName": { > "type": "string", > "description": "Optional display name." > }, > "resourceName": { > "type": "string", > "description": "Azure resource name. Defaults to the `AZURE_RESOURCE_NAME` environment variable." > }, > "token": { > "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 > } > ], > "description": "Optional API key to use with the model. Defaults to the `AZURE_API_KEY` environment variable." > }, > "apiVersion": { > "type": "string", > "description": "Sets a custom api version. Defaults to `preview`." > }, > "baseUrl": { > "type": "string", > "format": "url", > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$", > "description": "Use a different URL prefix for API calls. Either this or `resourceName` can be used." > }, > "reasoningEffort": { > "type": "string", > "description": "The reasoning effort to use with the model. Defaults to `medium`. See https://platform.openai.com/docs/guides/reasoning#get-started-with-reasonings", > "examples": [ > "none", > "minimal", > "low", > "medium", > "high" > ] > }, > "reasoningSummary": { > "type": "string", > "description": "Controls whether the model returns its reasoning process. Set to 'auto' for a condensed summary, 'detailed' for more comprehensive reasoning, or 'none' to disable. Defaults to 'auto'.", > "examples": [ > "none", > "auto", > "detailed" > ] > }, > "temperature": { > "type": "number", > "description": "Optional temperature setting to use with the model." > }, > "headers": { > "type": "object", > "description": "Optional headers to use with the model.", > "patternProperties": { > "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$": { > "anyOf": [ > { > "type": "string" > }, > { > "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 > } > ] > } > ] > } > }, > "additionalProperties": false > } > }, > "required": [ > "provider", > "model" > ], > "additionalProperties": false > }, > { > "type": "object", > "properties": { > "provider": { > "const": "deepseek", > "description": "DeepSeek Configuration" > }, > "model": { > "type": "string", > "description": "The name of the language model." > }, > "displayName": { > "type": "string", > "description": "Optional display name." > }, > "token": { > "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 > } > ], > "description": "Optional API key to use with the model. Defaults to the `DEEPSEEK_API_KEY` environment variable." > }, > "baseUrl": { > "type": "string", > "format": "url", > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$", > "description": "Optional base URL." > }, > "temperature": { > "type": "number", > "description": "Optional temperature setting to use with the model." > }, > "headers": { > "type": "object", > "description": "Optional headers to use with the model.", > "patternProperties": { > "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$": { > "anyOf": [ > { > "type": "string" > }, > { > "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 > } > ] > } > ] > } > }, > "additionalProperties": false > } > }, > "required": [ > "provider", > "model" > ], > "additionalProperties": false > }, > { > "type": "object", > "properties": { > "provider": { > "const": "google-generative-ai", > "description": "Google Generative AI Configuration" > }, > "model": { > "type": "string", > "description": "The name of the language model." > }, > "displayName": { > "type": "string", > "description": "Optional display name." > }, > "token": { > "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 > } > ], > "description": "Optional API key to use with the model. Defaults to the `GOOGLE_GENERATIVE_AI_API_KEY` environment variable." > }, > "baseUrl": { > "type": "string", > "format": "url", > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$", > "description": "Optional base URL." > }, > "thinkingLevel": { > "type": "string", > "description": "Optional thinking level for Gemini 3 models. Controls the depth of reasoning the model performs. See https://ai.google.dev/gemini-api/docs/thinking#thinking-levels", > "enum": [ > "minimal", > "low", > "medium", > "high" > ] > }, > "thinkingBudget": { > "type": "integer", > "description": "Optional thinking budget for Gemini 2.5 models. Sets the number of thinking tokens the model can use when generating a response. Set to -1 for dynamic thinking. See https://ai.google.dev/gemini-api/docs/thinking#set-budget" > }, > "temperature": { > "type": "number", > "description": "Optional temperature setting to use with the model." > }, > "headers": { > "type": "object", > "description": "Optional headers to use with the model.", > "patternProperties": { > "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$": { > "anyOf": [ > { > "type": "string" > }, > { > "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 > } > ] > } > ] > } > }, > "additionalProperties": false > } > }, > "required": [ > "provider", > "model" > ], > "additionalProperties": false > }, > { > "type": "object", > "properties": { > "provider": { > "const": "google-vertex-anthropic", > "description": "Google Vertex AI Anthropic Configuration" > }, > "model": { > "type": "string", > "description": "The name of the Anthropic language model running on Google Vertex.", > "examples": [ > "claude-sonnet-4" > ] > }, > "displayName": { > "type": "string", > "description": "Optional display name." > }, > "project": { > "type": "string", > "description": "The Google Cloud project ID. Defaults to the `GOOGLE_VERTEX_PROJECT` environment variable." > }, > "region": { > "type": "string", > "description": "The Google Cloud region. Defaults to the `GOOGLE_VERTEX_REGION` environment variable.", > "examples": [ > "us-central1", > "us-east1", > "europe-west1" > ] > }, > "credentials": { > "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 > } > ], > "description": "Optional file path to service account credentials JSON. Defaults to the `GOOGLE_APPLICATION_CREDENTIALS` environment variable or application default credentials." > }, > "baseUrl": { > "type": "string", > "format": "url", > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$", > "description": "Optional base URL." > }, > "temperature": { > "type": "number", > "description": "Optional temperature setting to use with the model." > }, > "headers": { > "type": "object", > "description": "Optional headers to use with the model.", > "patternProperties": { > "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$": { > "anyOf": [ > { > "type": "string" > }, > { > "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 > } > ] > } > ] > } > }, > "additionalProperties": false > } > }, > "required": [ > "provider", > "model" > ], > "additionalProperties": false > }, > { > "type": "object", > "properties": { > "provider": { > "const": "google-vertex", > "description": "Google Vertex AI Configuration" > }, > "model": { > "type": "string", > "description": "The name of the language model.", > "examples": [ > "gemini-2.0-flash-exp", > "gemini-1.5-pro", > "gemini-1.5-flash" > ] > }, > "displayName": { > "type": "string", > "description": "Optional display name." > }, > "project": { > "type": "string", > "description": "The Google Cloud project ID. Defaults to the `GOOGLE_VERTEX_PROJECT` environment variable." > }, > "region": { > "type": "string", > "description": "The Google Cloud region. Defaults to the `GOOGLE_VERTEX_REGION` environment variable.", > "examples": [ > "us-central1", > "us-east1", > "europe-west1" > ] > }, > "credentials": { > "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 > } > ], > "description": "Optional file path to service account credentials JSON. Defaults to the `GOOGLE_APPLICATION_CREDENTIALS` environment variable or application default credentials." > }, > "baseUrl": { > "type": "string", > "format": "url", > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$", > "description": "Optional base URL." > }, > "thinkingLevel": { > "type": "string", > "description": "Optional thinking level for Gemini 3 models. Controls the depth of reasoning the model performs. See https://ai.google.dev/gemini-api/docs/thinking#thinking-levels", > "enum": [ > "minimal", > "low", > "medium", > "high" > ] > }, > "thinkingBudget": { > "type": "integer", > "description": "Optional thinking budget for Gemini 2.5 models. Sets the number of thinking tokens the model can use when generating a response. Set to -1 for dynamic thinking. See https://ai.google.dev/gemini-api/docs/thinking#set-budget" > }, > "temperature": { > "type": "number", > "description": "Optional temperature setting to use with the model." > }, > "headers": { > "type": "object", > "description": "Optional headers to use with the model.", > "patternProperties": { > "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$": { > "anyOf": [ > { > "type": "string" > }, > { > "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 > } > ] > } > ] > } > }, > "additionalProperties": false > } > }, > "required": [ > "provider", > "model" > ], > "additionalProperties": false > }, > { > "type": "object", > "properties": { > "provider": { > "const": "mistral", > "description": "Mistral AI Configuration" > }, > "model": { > "type": "string", > "description": "The name of the language model." > }, > "displayName": { > "type": "string", > "description": "Optional display name." > }, > "token": { > "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 > } > ], > "description": "Optional API key to use with the model. Defaults to the `MISTRAL_API_KEY` environment variable." > }, > "baseUrl": { > "type": "string", > "format": "url", > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$", > "description": "Optional base URL." > }, > "temperature": { > "type": "number", > "description": "Optional temperature setting to use with the model." > }, > "headers": { > "type": "object", > "description": "Optional headers to use with the model.", > "patternProperties": { > "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$": { > "anyOf": [ > { > "type": "string" > }, > { > "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 > } > ] > } > ] > } > }, > "additionalProperties": false > } > }, > "required": [ > "provider", > "model" > ], > "additionalProperties": false > }, > { > "type": "object", > "properties": { > "provider": { > "const": "openai", > "description": "OpenAI Configuration" > }, > "model": { > "type": "string", > "description": "The name of the language model.", > "examples": [ > "gpt-4.1", > "o4-mini", > "o3", > "o3-deep-research" > ] > }, > "displayName": { > "type": "string", > "description": "Optional display name." > }, > "token": { > "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 > } > ], > "description": "Optional API key to use with the model. Defaults to the `OPENAI_API_KEY` environment variable." > }, > "baseUrl": { > "type": "string", > "format": "url", > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$", > "description": "Optional base URL." > }, > "reasoningEffort": { > "type": "string", > "description": "The reasoning effort to use with the model. Defaults to `medium`. See https://platform.openai.com/docs/guides/reasoning#get-started-with-reasonings", > "examples": [ > "none", > "minimal", > "low", > "medium", > "high" > ] > }, > "reasoningSummary": { > "type": "string", > "description": "Controls whether the model returns its reasoning process. Set to 'auto' for a condensed summary, 'detailed' for more comprehensive reasoning, or 'none' to disable. Defaults to 'auto'.", > "examples": [ > "none", > "auto", > "detailed" > ] > }, > "temperature": { > "type": "number", > "description": "Optional temperature setting to use with the model." > }, > "headers": { > "type": "object", > "description": "Optional headers to use with the model.", > "patternProperties": { > "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$": { > "anyOf": [ > { > "type": "string" > }, > { > "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 > } > ] > } > ] > } > }, > "additionalProperties": false > } > }, > "required": [ > "provider", > "model" > ], > "additionalProperties": false > }, > { > "type": "object", > "properties": { > "provider": { > "const": "openai-compatible", > "description": "OpenAI Compatible Configuration" > }, > "model": { > "type": "string", > "description": "The name of the language model." > }, > "displayName": { > "type": "string", > "description": "Optional display name." > }, > "token": { > "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 > } > ], > "description": "Optional API key. If specified, adds an `Authorization` header to request headers with the value Bearer ." > }, > "baseUrl": { > "type": "string", > "format": "url", > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$", > "description": "Base URL of the OpenAI-compatible chat completions API endpoint.", > "examples": [ > "http://localhost:8080/v1" > ] > }, > "headers": { > "type": "object", > "description": "Optional headers to use with the model.", > "patternProperties": { > "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$": { > "anyOf": [ > { > "type": "string" > }, > { > "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 > } > ] > } > ] > } > }, > "additionalProperties": false > }, > "queryParams": { > "type": "object", > "description": "Optional query parameters to include in the request url.", > "patternProperties": { > "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$": { > "anyOf": [ > { > "type": "string" > }, > { > "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 > } > ] > } > ] > } > }, > "additionalProperties": false > }, > "reasoningTag": { > "type": "string", > "description": "The name of the XML tag to extract reasoning from (without angle brackets). Defaults to `think`.", > "default": "think", > "examples": [ > "think", > "thinking", > "reasoning" > ] > }, > "temperature": { > "type": "number", > "description": "Optional temperature setting to use with the model." > } > }, > "required": [ > "provider", > "model", > "baseUrl" > ], > "additionalProperties": false > }, > { > "type": "object", > "properties": { > "provider": { > "const": "openrouter", > "description": "OpenRouter Configuration" > }, > "model": { > "type": "string", > "description": "The name of the language model." > }, > "displayName": { > "type": "string", > "description": "Optional display name." > }, > "token": { > "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 > } > ], > "description": "Optional API key to use with the model. Defaults to the `OPENROUTER_API_KEY` environment variable." > }, > "baseUrl": { > "type": "string", > "format": "url", > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$", > "description": "Optional base URL." > }, > "temperature": { > "type": "number", > "description": "Optional temperature setting to use with the model." > }, > "headers": { > "type": "object", > "description": "Optional headers to use with the model.", > "patternProperties": { > "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$": { > "anyOf": [ > { > "type": "string" > }, > { > "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 > } > ] > } > ] > } > }, > "additionalProperties": false > } > }, > "required": [ > "provider", > "model" > ], > "additionalProperties": false > }, > { > "type": "object", > "properties": { > "provider": { > "const": "xai", > "description": "xAI Configuration" > }, > "model": { > "type": "string", > "description": "The name of the language model.", > "examples": [ > "grok-beta", > "grok-vision-beta" > ] > }, > "displayName": { > "type": "string", > "description": "Optional display name." > }, > "token": { > "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 > } > ], > "description": "Optional API key to use with the model. Defaults to the `XAI_API_KEY` environment variable." > }, > "baseUrl": { > "type": "string", > "format": "url", > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$", > "description": "Optional base URL." > }, > "temperature": { > "type": "number", > "description": "Optional temperature setting to use with the model." > }, > "headers": { > "type": "object", > "description": "Optional headers to use with the model.", > "patternProperties": { > "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$": { > "anyOf": [ > { > "type": "string" > }, > { > "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 > } > ] > } > ] > } > }, > "additionalProperties": false > } > }, > "required": [ > "provider", > "model" > ], > "additionalProperties": false > } > ] > } > ``` # Structured Logging Source: https://docs.sourcebot.dev/docs/configuration/structured-logging By default, Sourcebot will output logs to the console in a human readable format. If you'd like Sourcebot to output structured JSON logs, set the following env vars: * `SOURCEBOT_STRUCTURED_LOGGING_ENABLED` (default: `false`): Controls whether logs are in a structured JSON format * `SOURCEBOT_STRUCTURED_LOGGING_FILE`: If structured logging is enabled and this env var is set, structured logs will be written to this file (ex. `/data/sourcebot.log`) ### Structured log schema ```json theme={null} { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "title": "SourcebotLog", "properties": { "level": { "type": "string", "description": "The log level (error, warning, info, debug)" }, "service": { "type": "string", "description": "The Sourcebot component that generated the log" }, "message": { "type": "string", "description": "The log message" }, "status": { "type": "string", "description": "The same value as the level field added for datadog support" }, "timestamp": { "type": "string", "description": "The timestamp of the log in ISO 8061 format" } } } ``` # Transactional Email Source: https://docs.sourcebot.dev/docs/configuration/transactional-emails To enable transactional emails in your deployment, set the following environment variables. We recommend using [Resend](https://resend.com/), but you can use any provider. Setting this enables you to: * Send emails when new members are invited * Send emails when organization join requests are created/accepted * Log into the Sourcebot deployment using [email codes](/docs/configuration/auth/authentication#email-codes) | Variable | Description | | :- | :- | | `SMTP_CONNECTION_URL` | SMTP server connection (`smtp://[user[:password]@]host[:port]`) | | `EMAIL_FROM_ADDRESS` | The sender's email address | You can also provide the SMTP connection details as individual environment variables instead of a full URL. | Variable | Description | | :- | :- | | `SMTP_HOST` | The hostname of the SMTP server | | `SMTP_PORT` | The port of the SMTP server | | `SMTP_USERNAME` | The username for SMTP authentication | | `SMTP_PASSWORD` | The password for SMTP authentication | | `EMAIL_FROM_ADDRESS` | The sender's email address | If `SMTP_CONNECTION_URL` is set, it takes precedence over the individual variables. # Linking code from Azure Devops Cloud Source: https://docs.sourcebot.dev/docs/connections/ado-cloud If you're not familiar with Sourcebot [connections](/docs/connections/indexing-your-code), please read that overview first. ## Permission syncing You can enforce repository access with [user-driven permission syncing](/docs/features/permission-syncing#azure-devops-cloud). Configure the [Azure DevOps Cloud identity provider](/docs/configuration/auth/sso#azure-devops-cloud) to authorize each user's access through Microsoft Entra OAuth. The PAT on this connection continues to handle repository discovery and indexing. ## Examples > **Sync individual repos** > > ```json theme={null} > { > "type": "azuredevops", > "deploymentType": "cloud", > "repos": [ > "organizationName/projectName/repoName", > "organizationName/projectName/repoName2 > ] > } > ``` > **Sync all repos in a organization** > > ```json theme={null} > { > "type": "azuredevops", > "deploymentType": "cloud", > "orgs": [ > "organizationName", > "organizationName2 > ] > } > ``` > **Sync all repos in a project** > > ```json theme={null} > { > "type": "azuredevops", > "deploymentType": "cloud", > "projects": [ > "organizationName/projectName", > "organizationName/projectName2" > ] > } > ``` > **Exclude repos from syncing** > > ```json theme={null} > { > "type": "azuredevops", > "deploymentType": "cloud", > // Include all repos in my-org... > "orgs": [ > "my-org" > ], > // ...except: > "exclude": { > // repos that are disabled > "disabled": true, > // repos that match these glob patterns > "repos": [ > "reposToExclude*" > ], > // projects that match these glob patterns > "projects": [ > "projectstoExclude*" > ] > // repos less than the defined min OR larger than the defined max > "size": { > // repos that are less than 1MB (in bytes)... > "min": 1048576, > // or repos greater than 100MB (in bytes) > "max": 104857600 > } > } > } > ``` ## Authenticating with Azure Devops Cloud 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](/docs/configuration/config-file#tokens) via an environment variable which is referenced in the `token` property: **Environment Variable** 1. Add the `token` property to your connection config: ```json theme={null} { "type": "azuredevops", "deploymentType": "cloud", "token": { // note: this env var can be named anything. It // doesn't need to be `ADO_TOKEN`. "env": "ADO_TOKEN" }, // At least one of the following is required to specify which repos to sync: "repos": ["organizationName/projectName/repoName"], // "orgs": ["organizationName"], // "projects": ["organizationName/projectName"] } ``` 2. Pass this environment variable each time you run Sourcebot: ```bash theme={null} docker run \ -e ADO_TOKEN= \ /* additional args */ \ docker.sourcebot.dev/sourcebot-dev/sourcebot:latest ``` ## Schema reference > **Reference** > > [schemas/v3/azuredevops.json](https://github.com/sourcebot-dev/sourcebot/blob/main/schemas/v3/azuredevops.json) > > ```json theme={null} > { > "$schema": "http://json-schema.org/draft-07/schema#", > "type": "object", > "title": "AzureDevOpsConnectionConfig", > "properties": { > "type": { > "const": "azuredevops", > "description": "Azure DevOps Configuration" > }, > "token": { > "description": "A Personal Access Token (PAT).", > "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 > } > ] > }, > "url": { > "type": "string", > "format": "url", > "default": "https://dev.azure.com", > "description": "The URL of the Azure DevOps host. For Azure DevOps Cloud, use https://dev.azure.com. For Azure DevOps Server, use your server URL.", > "examples": [ > "https://dev.azure.com", > "https://azuredevops.example.com" > ], > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$" > }, > "deploymentType": { > "type": "string", > "enum": [ > "cloud", > "server" > ], > "description": "The type of Azure DevOps deployment" > }, > "useTfsPath": { > "type": "boolean", > "default": false, > "description": "Use legacy TFS path format (/tfs) in API URLs. Required for older TFS installations (TFS 2018 and earlier). When true, API URLs will include /tfs in the path (e.g., https://server/tfs/collection/_apis/...)." > }, > "orgs": { > "type": "array", > "items": { > "type": "string", > "pattern": "^[\\w.-]+$" > }, > "default": [], > "examples": [ > [ > "my-org" > ] > ], > "description": "List of organizations to sync with. For Cloud, this is the organization name. For Server, this is the collection name. All projects and repositories visible to the provided `token` will be synced, unless explicitly defined in the `exclude` property." > }, > "projects": { > "type": "array", > "items": { > "type": "string", > "pattern": "^[\\w.-]+\\/[\\w. -]+$" > }, > "default": [], > "examples": [ > [ > "my-org/my-project", > "my-collection/my-project" > ] > ], > "description": "List of specific projects to sync with. Expected to be formatted as '{orgName}/{projectName}' for Cloud or '{collectionName}/{projectName}' for Server." > }, > "repos": { > "type": "array", > "items": { > "type": "string", > "pattern": "^[\\w.-]+\\/[\\w. -]+\\/[\\w. -]+$" > }, > "default": [], > "examples": [ > [ > "my-org/my-project/my-repo" > ] > ], > "description": "List of individual repositories to sync with. Expected to be formatted as '{orgName}/{projectName}/{repoName}'." > }, > "exclude": { > "type": "object", > "properties": { > "disabled": { > "type": "boolean", > "default": false, > "description": "Exclude disabled repositories from syncing." > }, > "repos": { > "type": "array", > "items": { > "type": "string" > }, > "default": [], > "description": "List of repositories to exclude from syncing. Glob patterns are supported." > }, > "projects": { > "type": "array", > "items": { > "type": "string" > }, > "default": [], > "description": "List of projects to exclude from syncing. Glob patterns are supported." > }, > "size": { > "type": "object", > "description": "Exclude repositories based on their size.", > "properties": { > "min": { > "type": "integer", > "description": "Minimum repository size (in bytes) to sync (inclusive). Repositories less than this size will be excluded from syncing." > }, > "max": { > "type": "integer", > "description": "Maximum repository size (in bytes) to sync (inclusive). Repositories greater than this size will be excluded from syncing." > } > }, > "additionalProperties": false > } > }, > "additionalProperties": false > }, > "revisions": { > "type": "object", > "description": "The revisions (branches, tags) that should be included when indexing. The default branch (HEAD) is always indexed. A maximum of 64 revisions can be indexed, with any additional revisions being ignored.", > "properties": { > "branches": { > "type": "array", > "description": "List of branches to include when indexing. For a given repo, only the branches that exist on the repo's remote *and* match at least one of the provided `branches` will be indexed. The default branch (HEAD) is always indexed. Glob patterns are supported. A maximum of 64 branches can be indexed, with any additional branches being ignored.", > "items": { > "type": "string" > }, > "examples": [ > [ > "main", > "release/*" > ], > [ > "**" > ] > ], > "default": [] > }, > "tags": { > "type": "array", > "description": "List of tags to include when indexing. For a given repo, only the tags that exist on the repo's remote *and* match at least one of the provided `tags` will be indexed. Glob patterns are supported. A maximum of 64 tags can be indexed, with any additional tags being ignored.", > "items": { > "type": "string" > }, > "examples": [ > [ > "latest", > "v2.*.*" > ], > [ > "**" > ] > ], > "default": [] > } > }, > "additionalProperties": false > }, > "enforcePermissions": { > "type": "boolean", > "description": "Controls whether repository permissions are enforced for this connection. When `PERMISSION_SYNC_ENABLED` is false, this setting has no effect. Defaults to the value of `PERMISSION_SYNC_ENABLED`. See https://docs.sourcebot.dev/docs/features/permission-syncing" > }, > "enforcePermissionsForPublicRepos": { > "type": "boolean", > "default": false, > "description": "Controls whether repository permissions are enforced for public repositories in this connection. When true, public repositories are only visible to users with a linked account for this connection's code host. When false, public repositories are visible to all users. Has no effect when enforcePermissions is false. Defaults to false. See https://docs.sourcebot.dev/docs/features/permission-syncing" > } > }, > "required": [ > "type", > "token", > "deploymentType" > ], > "additionalProperties": false > } > ``` # Linking code from Azure Devops Server Source: https://docs.sourcebot.dev/docs/connections/ado-server If you're not familiar with Sourcebot [connections](/docs/connections/indexing-your-code), please read that overview first. ## Examples > **Enable TFS path support** > > This is required if you're using an older version of ADO Server which has `/tfs` in the repo paths. > > ```json theme={null} > { > "type": "azuredevops", > "deploymentType": "server", > "useTfsPath": true, > "repos": [ > "organizationName/projectName/repoName", > "organizationName/projectName/repoName2 > ] > } > ``` > **Sync individual repos** > > ```json theme={null} > { > "type": "azuredevops", > "deploymentType": "server", > "repos": [ > "organizationName/projectName/repoName", > "organizationName/projectName/repoName2 > ] > } > ``` > **Sync all repos in a collection** > > ```json theme={null} > { > "type": "azuredevops", > "deploymentType": "server", > "orgs": [ > "collectionName", > "collectionName2" > ] > } > ``` > **Sync all repos in a project** > > ```json theme={null} > { > "type": "azuredevops", > "deploymentType": "server", > "projects": [ > "collectionName/projectName", > "collectionName/projectName2" > ] > } > ``` > **Exclude repos from syncing** > > ```json theme={null} > { > "type": "azuredevops", > "deploymentType": "server", > // Include all repos in my-org... > "orgs": [ > "my-org" > ], > // ...except: > "exclude": { > // repos that are disabled > "disabled": true, > // repos that match these glob patterns > "repos": [ > "reposToExclude*" > ], > // projects that match these glob patterns > "projects": [ > "projectstoExclude*" > ] > // repos less than the defined min OR larger than the defined max > "size": { > // repos that are less than 1MB (in bytes)... > "min": 1048576, > // or repos greater than 100MB (in bytes) > "max": 104857600 > } > } > } > ``` ## Authenticating with Azure Devops Server 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](/docs/configuration/config-file#tokens) via an environment variable which is referenced in the `token` property: **Environment Variable** 1. Add the `token` property to your connection config: ```json theme={null} { "type": "azuredevops", "deploymentType": "server", "token": { // note: this env var can be named anything. It // doesn't need to be `ADO_TOKEN`. "env": "ADO_TOKEN" }, // At least one of the following is required to specify which repos to sync: "repos": ["collectionName/projectName/repoName"], // "orgs": ["collectionName"], // "projects": ["collectionName/projectName"] } ``` 2. Pass this environment variable each time you run Sourcebot: ```bash theme={null} docker run \ -e ADO_TOKEN= \ /* additional args */ \ docker.sourcebot.dev/sourcebot-dev/sourcebot:latest ``` ## Schema reference > **Reference** > > [schemas/v3/azuredevops.json](https://github.com/sourcebot-dev/sourcebot/blob/main/schemas/v3/azuredevops.json) > > ```json theme={null} > { > "$schema": "http://json-schema.org/draft-07/schema#", > "type": "object", > "title": "AzureDevOpsConnectionConfig", > "properties": { > "type": { > "const": "azuredevops", > "description": "Azure DevOps Configuration" > }, > "token": { > "description": "A Personal Access Token (PAT).", > "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 > } > ] > }, > "url": { > "type": "string", > "format": "url", > "default": "https://dev.azure.com", > "description": "The URL of the Azure DevOps host. For Azure DevOps Cloud, use https://dev.azure.com. For Azure DevOps Server, use your server URL.", > "examples": [ > "https://dev.azure.com", > "https://azuredevops.example.com" > ], > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$" > }, > "deploymentType": { > "type": "string", > "enum": [ > "cloud", > "server" > ], > "description": "The type of Azure DevOps deployment" > }, > "useTfsPath": { > "type": "boolean", > "default": false, > "description": "Use legacy TFS path format (/tfs) in API URLs. Required for older TFS installations (TFS 2018 and earlier). When true, API URLs will include /tfs in the path (e.g., https://server/tfs/collection/_apis/...)." > }, > "orgs": { > "type": "array", > "items": { > "type": "string", > "pattern": "^[\\w.-]+$" > }, > "default": [], > "examples": [ > [ > "my-org" > ] > ], > "description": "List of organizations to sync with. For Cloud, this is the organization name. For Server, this is the collection name. All projects and repositories visible to the provided `token` will be synced, unless explicitly defined in the `exclude` property." > }, > "projects": { > "type": "array", > "items": { > "type": "string", > "pattern": "^[\\w.-]+\\/[\\w. -]+$" > }, > "default": [], > "examples": [ > [ > "my-org/my-project", > "my-collection/my-project" > ] > ], > "description": "List of specific projects to sync with. Expected to be formatted as '{orgName}/{projectName}' for Cloud or '{collectionName}/{projectName}' for Server." > }, > "repos": { > "type": "array", > "items": { > "type": "string", > "pattern": "^[\\w.-]+\\/[\\w. -]+\\/[\\w. -]+$" > }, > "default": [], > "examples": [ > [ > "my-org/my-project/my-repo" > ] > ], > "description": "List of individual repositories to sync with. Expected to be formatted as '{orgName}/{projectName}/{repoName}'." > }, > "exclude": { > "type": "object", > "properties": { > "disabled": { > "type": "boolean", > "default": false, > "description": "Exclude disabled repositories from syncing." > }, > "repos": { > "type": "array", > "items": { > "type": "string" > }, > "default": [], > "description": "List of repositories to exclude from syncing. Glob patterns are supported." > }, > "projects": { > "type": "array", > "items": { > "type": "string" > }, > "default": [], > "description": "List of projects to exclude from syncing. Glob patterns are supported." > }, > "size": { > "type": "object", > "description": "Exclude repositories based on their size.", > "properties": { > "min": { > "type": "integer", > "description": "Minimum repository size (in bytes) to sync (inclusive). Repositories less than this size will be excluded from syncing." > }, > "max": { > "type": "integer", > "description": "Maximum repository size (in bytes) to sync (inclusive). Repositories greater than this size will be excluded from syncing." > } > }, > "additionalProperties": false > } > }, > "additionalProperties": false > }, > "revisions": { > "type": "object", > "description": "The revisions (branches, tags) that should be included when indexing. The default branch (HEAD) is always indexed. A maximum of 64 revisions can be indexed, with any additional revisions being ignored.", > "properties": { > "branches": { > "type": "array", > "description": "List of branches to include when indexing. For a given repo, only the branches that exist on the repo's remote *and* match at least one of the provided `branches` will be indexed. The default branch (HEAD) is always indexed. Glob patterns are supported. A maximum of 64 branches can be indexed, with any additional branches being ignored.", > "items": { > "type": "string" > }, > "examples": [ > [ > "main", > "release/*" > ], > [ > "**" > ] > ], > "default": [] > }, > "tags": { > "type": "array", > "description": "List of tags to include when indexing. For a given repo, only the tags that exist on the repo's remote *and* match at least one of the provided `tags` will be indexed. Glob patterns are supported. A maximum of 64 tags can be indexed, with any additional tags being ignored.", > "items": { > "type": "string" > }, > "examples": [ > [ > "latest", > "v2.*.*" > ], > [ > "**" > ] > ], > "default": [] > } > }, > "additionalProperties": false > }, > "enforcePermissions": { > "type": "boolean", > "description": "Controls whether repository permissions are enforced for this connection. When `PERMISSION_SYNC_ENABLED` is false, this setting has no effect. Defaults to the value of `PERMISSION_SYNC_ENABLED`. See https://docs.sourcebot.dev/docs/features/permission-syncing" > }, > "enforcePermissionsForPublicRepos": { > "type": "boolean", > "default": false, > "description": "Controls whether repository permissions are enforced for public repositories in this connection. When true, public repositories are only visible to users with a linked account for this connection's code host. When false, public repositories are visible to all users. Has no effect when enforcePermissions is false. Defaults to false. See https://docs.sourcebot.dev/docs/features/permission-syncing" > } > }, > "required": [ > "type", > "token", > "deploymentType" > ], > "additionalProperties": false > } > ``` # Linking code from Bitbucket Cloud Source: https://docs.sourcebot.dev/docs/connections/bitbucket-cloud > [!NOTE] > > Looking for docs on Bitbucket Data Center? See [this doc](/docs/connections/bitbucket-data-center). If you're not familiar with Sourcebot [connections](/docs/connections/indexing-your-code), please read that overview first. ## Examples > **Sync individual repos** > > ```json theme={null} > { > "type": "bitbucket", > "deploymentType": "cloud", > "repos": [ > "myWorkspace/myRepo" > ] > } > ``` > **Sync all repos in a workspace** > > ```json theme={null} > { > "type": "bitbucket", > "deploymentType": "cloud", > "workspaces": [ > "myWorkspace" > ] > } > ``` > **Sync all repos in a project** > > ```json theme={null} > { > "type": "bitbucket", > "deploymentType": "cloud", > "projects": [ > "myProject" > ] > } > ``` > **Exclude repos from syncing** > > ```json theme={null} > { > "type": "bitbucket", > "deploymentType": "cloud", > // Include all repos in my-workspace... > "workspaces": [ > "myWorkspace" > ], > // ...except: > "exclude": { > // repos that are archived > "archived": true, > // repos that are forks > "forks": true, > // repos that match these glob patterns > "repos": [ > "myWorkspace/repo1", > "myWorkspace2/*" > ] > } > } > ``` ## Authenticating with Bitbucket Cloud 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 `API Token`, `Access Token`, or `App Password`. **API Token** 1. Navigate to [Personal Settings → API tokens](https://id.atlassian.com/manage-profile/security/api-tokens) and click **Create API token with scopes**. Give the token a name and set an expiry date. 2. Select **Bitbucket** as the app. 3. Select the following scopes: * `read:repository:bitbucket` — View your repositories * `read:workspace:bitbucket` — View your workspaces 4. Click **Create token** and copy the token value. 5. Add the `user` (your account email), `gitUser` (your Bitbucket username), and `token` to your connection config. [Learn why both are needed](https://support.atlassian.com/bitbucket-cloud/docs/using-api-tokens/) ```json theme={null} { "type": "bitbucket", "deploymentType": "cloud", "user": "you@example.com", "gitUser": "myusername", "token": { // note: this env var can be named anything. It // doesn't need to be `BITBUCKET_TOKEN`. "env": "BITBUCKET_TOKEN" }, // At least one of the following is required to specify which repos to sync: "repos": ["myWorkspace/myRepo"], // "workspaces": ["myWorkspace"], // "projects": ["myProject"] } ``` 6. Pass this environment variable each time you run Sourcebot: ```bash theme={null} docker run \ -e BITBUCKET_TOKEN= \ /* additional args */ \ docker.sourcebot.dev/sourcebot-dev/sourcebot:latest ``` **Access Token** Create an access token for the desired scope (repo, project, or workspace). Visit the official [Bitbucket Cloud docs](https://support.atlassian.com/bitbucket-cloud/docs/access-tokens/) for more info. 1. Add the `token` property to your connection config: ```json theme={null} { "type": "bitbucket", "deploymentType": "cloud", "token": { // note: this env var can be named anything. It // doesn't need to be `BITBUCKET_TOKEN`. "env": "BITBUCKET_TOKEN" }, // At least one of the following is required to specify which repos to sync: "repos": ["myWorkspace/myRepo"], // "workspaces": ["myWorkspace"], // "projects": ["myProject"] } ``` 2. Pass this environment variable each time you run Sourcebot: ```bash theme={null} docker run \ -e BITBUCKET_TOKEN= \ /* additional args */ \ docker.sourcebot.dev/sourcebot-dev/sourcebot:latest ``` **App Password** > [!WARNING] > > App Passwords are deprecated. Atlassian recommends migrating to API tokens. [Learn more](https://www.atlassian.com/blog/bitbucket/bitbucket-cloud-transitions-to-api-tokens-enhancing-security-with-app-password-deprecation) Navigate to the [app password creation page](https://bitbucket.org/account/settings/app-passwords/) and create an app password. Ensure that it has the proper permissions for the scope of info you want to fetch (i.e. workspace, project, and/or repo level) ![Bitbucket App Password Permissions](https://mintcdn.com/sourcebot/8vfJfQmq9Ve6HNrE/images/bitbucket_app_password_perms.png?fit=max\&auto=format\&n=8vfJfQmq9Ve6HNrE\&q=85\&s=91340a06cb1ba1fbd0f42c58feacf5da) 1. Add the `user` (your Bitbucket username) and `token` properties to your connection config: ```json theme={null} { "type": "bitbucket", "deploymentType": "cloud", "user": "myusername", "token": { // note: this env var can be named anything. It // doesn't need to be `BITBUCKET_TOKEN`. "env": "BITBUCKET_TOKEN" }, // At least one of the following is required to specify which repos to sync: "repos": ["myWorkspace/myRepo"], // "workspaces": ["myWorkspace"], // "projects": ["myProject"] } ``` 2. Pass this environment variable each time you run Sourcebot: ```bash theme={null} docker run \ -e BITBUCKET_TOKEN= \ /* additional args */ \ docker.sourcebot.dev/sourcebot-dev/sourcebot:latest ``` ## Schema reference > **Reference** > > [schemas/v3/bitbucket.json](https://github.com/sourcebot-dev/sourcebot/blob/main/schemas/v3/bitbucket.json) > > ```json theme={null} > { > "$schema": "http://json-schema.org/draft-07/schema#", > "type": "object", > "title": "BitbucketConnectionConfig", > "properties": { > "type": { > "const": "bitbucket", > "description": "Bitbucket configuration" > }, > "user": { > "type": "string", > "description": "The username to use for API authentication. For app passwords, this is your Bitbucket username. For API tokens, this is your Bitbucket account email address." > }, > "gitUser": { > "type": "string", > "description": "The username to use for git clone authentication over HTTPS. If not set, falls back to 'user'. For API tokens, this is your Bitbucket username" > }, > "token": { > "description": "An authentication token.", > "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 > } > ] > }, > "url": { > "type": "string", > "format": "url", > "default": "https://api.bitbucket.org/2.0", > "description": "Bitbucket URL", > "examples": [ > "https://bitbucket.example.com" > ], > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$" > }, > "deploymentType": { > "type": "string", > "enum": [ > "cloud", > "server" > ], > "default": "cloud", > "description": "The type of Bitbucket deployment" > }, > "all": { > "type": "boolean", > "default": false, > "description": "Sync all repositories visible to the provided `token` (if any) in the Bitbucket Server instance. This option is ignored if `deploymentType` is `cloud`." > }, > "workspaces": { > "type": "array", > "items": { > "type": "string" > }, > "description": "List of workspaces to sync. Ignored if deploymentType is server." > }, > "projects": { > "type": "array", > "items": { > "type": "string" > }, > "description": "List of projects to sync" > }, > "repos": { > "type": "array", > "items": { > "type": "string" > }, > "description": "List of repos to sync" > }, > "exclude": { > "type": "object", > "properties": { > "archived": { > "type": "boolean", > "default": false, > "description": "Exclude archived repositories from syncing." > }, > "forks": { > "type": "boolean", > "default": false, > "description": "Exclude forked repositories from syncing." > }, > "repos": { > "type": "array", > "items": { > "type": "string" > }, > "examples": [ > [ > "cloud_workspace/PROJECT_KEY/repo1", > "SERVER_PROJECT_KEY/repo2" > ] > ], > "description": "List of specific repos to exclude from syncing." > } > }, > "additionalProperties": false > }, > "revisions": { > "type": "object", > "description": "The revisions (branches, tags) that should be included when indexing. The default branch (HEAD) is always indexed. A maximum of 64 revisions can be indexed, with any additional revisions being ignored.", > "properties": { > "branches": { > "type": "array", > "description": "List of branches to include when indexing. For a given repo, only the branches that exist on the repo's remote *and* match at least one of the provided `branches` will be indexed. The default branch (HEAD) is always indexed. Glob patterns are supported. A maximum of 64 branches can be indexed, with any additional branches being ignored.", > "items": { > "type": "string" > }, > "examples": [ > [ > "main", > "release/*" > ], > [ > "**" > ] > ], > "default": [] > }, > "tags": { > "type": "array", > "description": "List of tags to include when indexing. For a given repo, only the tags that exist on the repo's remote *and* match at least one of the provided `tags` will be indexed. Glob patterns are supported. A maximum of 64 tags can be indexed, with any additional tags being ignored.", > "items": { > "type": "string" > }, > "examples": [ > [ > "latest", > "v2.*.*" > ], > [ > "**" > ] > ], > "default": [] > } > }, > "additionalProperties": false > }, > "enforcePermissions": { > "type": "boolean", > "description": "Controls whether repository permissions are enforced for this connection. When `PERMISSION_SYNC_ENABLED` is false, this setting has no effect. Defaults to the value of `PERMISSION_SYNC_ENABLED`. See https://docs.sourcebot.dev/docs/features/permission-syncing" > }, > "enforcePermissionsForPublicRepos": { > "type": "boolean", > "default": false, > "description": "Controls whether repository permissions are enforced for public repositories in this connection. When true, public repositories are only visible to users with a linked account for this connection's code host. When false, public repositories are visible to all users. Has no effect when enforcePermissions is false. Defaults to false. See https://docs.sourcebot.dev/docs/features/permission-syncing" > } > }, > "required": [ > "type" > ], > "if": { > "properties": { > "deploymentType": { > "const": "server" > } > } > }, > "then": { > "required": [ > "url" > ] > }, > "additionalProperties": false > } > ``` # Linking code from Bitbucket Data Center Source: https://docs.sourcebot.dev/docs/connections/bitbucket-data-center > [!NOTE] > > Looking for docs on Bitbucket Cloud? See [this doc](/docs/connections/bitbucket-cloud). If you're not familiar with Sourcebot [connections](/docs/connections/indexing-your-code), please read that overview first. ## Examples > **Sync individual repos** > > ```json theme={null} > { > "type": "bitbucket", > "deploymentType": "server", > "url": "https://mybitbucketdeployment.com", > "repos": [ > "myProject/myRepo" > ] > } > ``` > **Sync all repos in a project** > > ```json theme={null} > { > "type": "bitbucket", > "deploymentType": "server", > "url": "https://mybitbucketdeployment.com", > "projects": [ > "myProject" > ] > } > ``` > **Sync all repos** > > > [!NOTE] > > > > Requires a `token` to be set in order to access private repositories. > > ```json theme={null} > { > "type": "bitbucket", > "deploymentType": "server", > "url": "https://mybitbucketdeployment.com", > // Index all repos visible to the provided token > "all": true > } > ``` > **Exclude repos from syncing** > > ```json theme={null} > { > "type": "bitbucket", > "deploymentType": "server", > "url": "https://mybitbucketdeployment.com", > // Include all repos in myProject... > "projects": [ > "myProject" > ], > // ...except: > "exclude": { > // repos that are archived > "archived": true, > // repos that are forks > "forks": true, > // repos that match these glob patterns > "repos": [ > "myProject/repo1", > "myProject2/*" > ] > } > } > ``` ## Authenticating with Bitbucket Data Center In order to index private repositories, you'll need to provide a [HTTP Access Token](https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html). Tokens can be scoped to a user account, a project, or an individual repository. Only repositories visible to the token will be able to be indexed by Sourcebot. > [!NOTE] > > If [permission syncing](/docs/features/permission-syncing#bitbucket-data-center) is enabled, the token must have **Repository Admin** permissions so Sourcebot can read repository-level user permissions. **User account token** User account tokens grant access to all repositories the user can access. Because these are tied to a specific user account, you must also set the `user` field to that user's username. 1. In Bitbucket Data Center, navigate to your profile → **Manage account** → **HTTP access tokens** and click **Create token**. Give it a name and grant it **Project read** and **Repository read** permissions. 2. Add the `user` (your Bitbucket username) and `token` properties to your connection config: ```json theme={null} { "type": "bitbucket", "deploymentType": "server", "url": "https://mybitbucketdeployment.com", "user": "myusername", "token": { // note: this env var can be named anything. It // doesn't need to be `BITBUCKET_TOKEN`. "env": "BITBUCKET_TOKEN" }, // At least one of the following is required to specify which repos to sync: "repos": ["myProject/myRepo"], // "projects": ["myProject"], // "all": true } ``` 3. Pass this environment variable each time you run Sourcebot: ```bash theme={null} docker run \ -e BITBUCKET_TOKEN= \ /* additional args */ \ docker.sourcebot.dev/sourcebot-dev/sourcebot:latest ``` **Project / repository token** Project and repository tokens are scoped to a specific project or repository. 1. In Bitbucket Data Center, navigate to the project or repository → **Settings** → **HTTP access tokens** and click **Create token**. Give it a name and grant it **Repository read** and **Project read** permissions. 2. Add the `token` property to your connection config: ```json theme={null} { "type": "bitbucket", "deploymentType": "server", "url": "https://mybitbucketdeployment.com", "token": { // note: this env var can be named anything. It // doesn't need to be `BITBUCKET_TOKEN`. "env": "BITBUCKET_TOKEN" }, // At least one of the following is required to specify which repos to sync: "repos": ["myProject/myRepo"], // "projects": ["myProject"], // "all": true } ``` 3. Pass this environment variable each time you run Sourcebot: ```bash theme={null} docker run \ -e BITBUCKET_TOKEN= \ /* additional args */ \ docker.sourcebot.dev/sourcebot-dev/sourcebot:latest ``` ## Rate limiting Bitbucket Data Center supports [rate limiting](https://confluence.atlassian.com/bitbucketserver094/improving-instance-stability-with-rate-limiting-1489803023.html) to protect instance stability. Rate limiting applies to HTTP requests with basic or bearer authentication, which includes the REST API calls Sourcebot makes to sync repositories. If rate limiting is enabled on your instance, Sourcebot may receive `HTTP 429 (Too Many Requests)` errors during sync. To prevent this, add a rate limiting exemption for the user (service account) whose token is used in your connection config. To add an exemption: 1. In Bitbucket Data Center, go to **Administration** → **Rate limiting** → **Exemptions** tab. 2. Click **Add exemption** and find the service account user. 3. Select **Allow unlimited requests** (recommended) or set a custom token bucket size and refill rate appropriate for your sync volume. 4. Click **Save**. ![Bitbucket Data Center rate limiting exemptions tab showing a user with unlimited requests](https://mintcdn.com/sourcebot/HN3U1hNIDFKT4nmq/images/bitbucket_rate_limit.png?fit=max\&auto=format\&n=HN3U1hNIDFKT4nmq\&q=85\&s=4f2725705e1331f474ac64b5fb6a8572) ## Troubleshooting If you're seeing errors like `TypeError: fetch failed` when fetching repo info, it may be that Sourcebot is refusing to connect to your self-hosted Bitbucket instance due to unrecognized SSL certs. Try setting the `NODE_TLS_REJECT_UNAUTHORIZED=0` environment variable or providing Sourcebot your certs through the `NODE_EXTRA_CA_CERTS` environment variable. ## Schema reference > **Reference** > > [schemas/v3/bitbucket.json](https://github.com/sourcebot-dev/sourcebot/blob/main/schemas/v3/bitbucket.json) > > ```json theme={null} > { > "$schema": "http://json-schema.org/draft-07/schema#", > "type": "object", > "title": "BitbucketConnectionConfig", > "properties": { > "type": { > "const": "bitbucket", > "description": "Bitbucket configuration" > }, > "user": { > "type": "string", > "description": "The username to use for API authentication. For app passwords, this is your Bitbucket username. For API tokens, this is your Bitbucket account email address." > }, > "gitUser": { > "type": "string", > "description": "The username to use for git clone authentication over HTTPS. If not set, falls back to 'user'. For API tokens, this is your Bitbucket username" > }, > "token": { > "description": "An authentication token.", > "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 > } > ] > }, > "url": { > "type": "string", > "format": "url", > "default": "https://api.bitbucket.org/2.0", > "description": "Bitbucket URL", > "examples": [ > "https://bitbucket.example.com" > ], > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$" > }, > "deploymentType": { > "type": "string", > "enum": [ > "cloud", > "server" > ], > "default": "cloud", > "description": "The type of Bitbucket deployment" > }, > "all": { > "type": "boolean", > "default": false, > "description": "Sync all repositories visible to the provided `token` (if any) in the Bitbucket Server instance. This option is ignored if `deploymentType` is `cloud`." > }, > "workspaces": { > "type": "array", > "items": { > "type": "string" > }, > "description": "List of workspaces to sync. Ignored if deploymentType is server." > }, > "projects": { > "type": "array", > "items": { > "type": "string" > }, > "description": "List of projects to sync" > }, > "repos": { > "type": "array", > "items": { > "type": "string" > }, > "description": "List of repos to sync" > }, > "exclude": { > "type": "object", > "properties": { > "archived": { > "type": "boolean", > "default": false, > "description": "Exclude archived repositories from syncing." > }, > "forks": { > "type": "boolean", > "default": false, > "description": "Exclude forked repositories from syncing." > }, > "repos": { > "type": "array", > "items": { > "type": "string" > }, > "examples": [ > [ > "cloud_workspace/PROJECT_KEY/repo1", > "SERVER_PROJECT_KEY/repo2" > ] > ], > "description": "List of specific repos to exclude from syncing." > } > }, > "additionalProperties": false > }, > "revisions": { > "type": "object", > "description": "The revisions (branches, tags) that should be included when indexing. The default branch (HEAD) is always indexed. A maximum of 64 revisions can be indexed, with any additional revisions being ignored.", > "properties": { > "branches": { > "type": "array", > "description": "List of branches to include when indexing. For a given repo, only the branches that exist on the repo's remote *and* match at least one of the provided `branches` will be indexed. The default branch (HEAD) is always indexed. Glob patterns are supported. A maximum of 64 branches can be indexed, with any additional branches being ignored.", > "items": { > "type": "string" > }, > "examples": [ > [ > "main", > "release/*" > ], > [ > "**" > ] > ], > "default": [] > }, > "tags": { > "type": "array", > "description": "List of tags to include when indexing. For a given repo, only the tags that exist on the repo's remote *and* match at least one of the provided `tags` will be indexed. Glob patterns are supported. A maximum of 64 tags can be indexed, with any additional tags being ignored.", > "items": { > "type": "string" > }, > "examples": [ > [ > "latest", > "v2.*.*" > ], > [ > "**" > ] > ], > "default": [] > } > }, > "additionalProperties": false > }, > "enforcePermissions": { > "type": "boolean", > "description": "Controls whether repository permissions are enforced for this connection. When `PERMISSION_SYNC_ENABLED` is false, this setting has no effect. Defaults to the value of `PERMISSION_SYNC_ENABLED`. See https://docs.sourcebot.dev/docs/features/permission-syncing" > }, > "enforcePermissionsForPublicRepos": { > "type": "boolean", > "default": false, > "description": "Controls whether repository permissions are enforced for public repositories in this connection. When true, public repositories are only visible to users with a linked account for this connection's code host. When false, public repositories are visible to all users. Has no effect when enforcePermissions is false. Defaults to false. See https://docs.sourcebot.dev/docs/features/permission-syncing" > } > }, > "required": [ > "type" > ], > "if": { > "properties": { > "deploymentType": { > "const": "server" > } > } > }, > "then": { > "required": [ > "url" > ] > }, > "additionalProperties": false > } > ``` # Other Git hosts Source: https://docs.sourcebot.dev/docs/connections/generic-git-host Sourcebot can sync code from any Git host (by clone url). This is helpful when you want to search code that not in a [supported code host](/docs/connections/indexing-your-code#platform-connection-guides). If you're not familiar with Sourcebot [connections](/docs/connections/indexing-your-code), please read that overview first. ## Getting Started To connect to a Git host, create a new [connection](/docs/connections/indexing-your-code) with type `git` and specify the clone url in the `url` property. For example: ```json theme={null} { "type": "git", "url": "https://github.com/sourcebot-dev/sourcebot" } ``` Note that only `http` & `https` URLs are supported at this time. ## Schema reference > **Reference** > > [schemas/v3/genericGitHost.json](https://github.com/sourcebot-dev/sourcebot/blob/main/schemas/v3/genericGitHost.json) > > ```json theme={null} > { > "$schema": "http://json-schema.org/draft-07/schema#", > "type": "object", > "title": "GenericGitHostConnectionConfig", > "properties": { > "type": { > "const": "git", > "description": "Generic Git host configuration" > }, > "url": { > "type": "string", > "format": "url", > "description": "The URL to the git repository. This can either be a remote URL (prefixed with `http://` or `https://`) or a absolute path to a directory on the local machine (prefixed with `file://`). If a local directory is specified, it must point to the root of a git repository. Local directories are treated as read-only modified. Local directories support glob patterns.", > "pattern": "^(https?:\\/\\/[^\\s/$.?#].[^\\s]*|file:\\/\\/\\/[^\\s]+)$", > "examples": [ > "https://github.com/sourcebot-dev/sourcebot", > "file:///path/to/repo", > "file:///repos/*" > ] > }, > "revisions": { > "type": "object", > "description": "The revisions (branches, tags) that should be included when indexing. The default branch (HEAD) is always indexed. A maximum of 64 revisions can be indexed, with any additional revisions being ignored.", > "properties": { > "branches": { > "type": "array", > "description": "List of branches to include when indexing. For a given repo, only the branches that exist on the repo's remote *and* match at least one of the provided `branches` will be indexed. The default branch (HEAD) is always indexed. Glob patterns are supported. A maximum of 64 branches can be indexed, with any additional branches being ignored.", > "items": { > "type": "string" > }, > "examples": [ > [ > "main", > "release/*" > ], > [ > "**" > ] > ], > "default": [] > }, > "tags": { > "type": "array", > "description": "List of tags to include when indexing. For a given repo, only the tags that exist on the repo's remote *and* match at least one of the provided `tags` will be indexed. Glob patterns are supported. A maximum of 64 tags can be indexed, with any additional tags being ignored.", > "items": { > "type": "string" > }, > "examples": [ > [ > "latest", > "v2.*.*" > ], > [ > "**" > ] > ], > "default": [] > } > }, > "additionalProperties": false > }, > "enforcePermissions": { > "type": "boolean", > "description": "Controls whether repository permissions are enforced for this connection. When `PERMISSION_SYNC_ENABLED` is false, this setting has no effect. Defaults to the value of `PERMISSION_SYNC_ENABLED`. See https://docs.sourcebot.dev/docs/features/permission-syncing" > }, > "enforcePermissionsForPublicRepos": { > "type": "boolean", > "default": false, > "description": "Controls whether repository permissions are enforced for public repositories in this connection. When true, public repositories are only visible to users with a linked account for this connection's code host. When false, public repositories are visible to all users. Has no effect when enforcePermissions is false. Defaults to false. See https://docs.sourcebot.dev/docs/features/permission-syncing" > } > }, > "required": [ > "type", > "url" > ], > "additionalProperties": false > } > ``` # Linking code from Gerrit Source: https://docs.sourcebot.dev/docs/connections/gerrit > [!NOTE] > > Authenticating with Gerrit is currently not supported. If you need this capability, please raise a [feature request](https://github.com/sourcebot-dev/sourcebot/issues/new?template=feature_request.md). Sourcebot can sync code from self-hosted gerrit instances. If you're not familiar with Sourcebot [connections](/docs/connections/indexing-your-code), please read that overview first. ## Connecting to a Gerrit instance To connect to a gerrit instance, provide the `url` property to your config: ```json theme={null} { "type": "gerrit", "url": "https://gerrit.example.com", // Specify which projects to sync using glob patterns: "projects": ["project1/**"] } ``` ## Examples > **Sync projects by glob pattern** > > ```json theme={null} > { > "type": "gerrit", > "url": "https://gerrit.example.com", > // Sync all repos under project1 and project2/sub-project > "projects": [ > "project1/**", > "project2/sub-project/**" > ] > } > ``` > **Exclude repos from syncing** > > ```json theme={null} > { > "type": "gerrit", > "url": "https://gerrit.example.com", > // Sync all repos under project1 and project2/sub-project... > "projects": [ > "project1/**", > "project2/sub-project/**" > ], > // ...except: > "exclude": { > // any project that matches these glob patterns > "projects": [ > "project1/foo-project", > "project2/sub-project/some-sub-folder/**" > ], > > // projects that have state READ_ONLY > "readOnly": true, > > // projects that have state HIDDEN > "hidden": true > } > } > ``` ## Schema reference > **Reference** > > [schemas/v3/gerrit.json](https://github.com/sourcebot-dev/sourcebot/blob/main/schemas/v3/gerrit.json) > > ```json theme={null} > { > "$schema": "http://json-schema.org/draft-07/schema#", > "type": "object", > "title": "GerritConnectionConfig", > "properties": { > "type": { > "const": "gerrit", > "description": "Gerrit Configuration" > }, > "url": { > "type": "string", > "format": "url", > "description": "The URL of the Gerrit host.", > "examples": [ > "https://gerrit.example.com" > ], > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$" > }, > "projects": { > "type": "array", > "items": { > "type": "string" > }, > "description": "List of specific projects to sync. If not specified, all projects will be synced. Glob patterns are supported", > "examples": [ > [ > "project1/repo1", > "project2/**" > ] > ] > }, > "exclude": { > "type": "object", > "properties": { > "projects": { > "type": "array", > "items": { > "type": "string" > }, > "examples": [ > [ > "project1/repo1", > "project2/**" > ] > ], > "description": "List of specific projects to exclude from syncing." > }, > "readOnly": { > "type": "boolean", > "default": false, > "description": "Exclude read-only projects from syncing." > }, > "hidden": { > "type": "boolean", > "default": false, > "description": "Exclude hidden projects from syncing." > } > }, > "additionalProperties": false > }, > "revisions": { > "type": "object", > "description": "The revisions (branches, tags) that should be included when indexing. The default branch (HEAD) is always indexed. A maximum of 64 revisions can be indexed, with any additional revisions being ignored.", > "properties": { > "branches": { > "type": "array", > "description": "List of branches to include when indexing. For a given repo, only the branches that exist on the repo's remote *and* match at least one of the provided `branches` will be indexed. The default branch (HEAD) is always indexed. Glob patterns are supported. A maximum of 64 branches can be indexed, with any additional branches being ignored.", > "items": { > "type": "string" > }, > "examples": [ > [ > "main", > "release/*" > ], > [ > "**" > ] > ], > "default": [] > }, > "tags": { > "type": "array", > "description": "List of tags to include when indexing. For a given repo, only the tags that exist on the repo's remote *and* match at least one of the provided `tags` will be indexed. Glob patterns are supported. A maximum of 64 tags can be indexed, with any additional tags being ignored.", > "items": { > "type": "string" > }, > "examples": [ > [ > "latest", > "v2.*.*" > ], > [ > "**" > ] > ], > "default": [] > } > }, > "additionalProperties": false > }, > "enforcePermissions": { > "type": "boolean", > "description": "Controls whether repository permissions are enforced for this connection. When `PERMISSION_SYNC_ENABLED` is false, this setting has no effect. Defaults to the value of `PERMISSION_SYNC_ENABLED`. See https://docs.sourcebot.dev/docs/features/permission-syncing" > }, > "enforcePermissionsForPublicRepos": { > "type": "boolean", > "default": false, > "description": "Controls whether repository permissions are enforced for public repositories in this connection. When true, public repositories are only visible to users with a linked account for this connection's code host. When false, public repositories are visible to all users. Has no effect when enforcePermissions is false. Defaults to false. See https://docs.sourcebot.dev/docs/features/permission-syncing" > } > }, > "required": [ > "type", > "url" > ], > "additionalProperties": false > } > ``` # Linking code from Gitea Source: https://docs.sourcebot.dev/docs/connections/gitea Sourcebot can sync code from Gitea Cloud, and self-hosted. If you're not familiar with Sourcebot [connections](/docs/connections/indexing-your-code), please read that overview first. ## Examples > **Sync individual repos** > > ```json theme={null} > { > "type": "gitea", > "repos": [ > "sourcebot-dev/sourcebot", > "getsentry/sentry", > "torvalds/linux" > ] > } > ``` > **Sync all repos in a organization** > > ```json theme={null} > { > "type": "gitea", > "orgs": [ > "sourcebot-dev", > "getsentry", > "vercel" > ] > } > ``` > **Sync all repos owned by a user** > > ```json theme={null} > { > "type": "gitea", > "users": [ > "torvalds", > "ggerganov" > ] > } > ``` > **Exclude repos from syncing** > > ```json theme={null} > { > "type": "gitea", > // 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-*/**" > ] > } > } > ``` ## Authenticating with Gitea In order to index private repositories, you'll need to generate a Gitea access token. Generate a Gitea access token [here](http://gitea.com/user/settings/applications). At minimum, you'll need to select the `read:repository` scope. `read:user` and `read:organization` are required for the `user` and `org` fields of your config file: ![Gitea Access token creation](https://mintcdn.com/sourcebot/8vfJfQmq9Ve6HNrE/images/gitea_pat_creation.png?fit=max\&auto=format\&n=8vfJfQmq9Ve6HNrE\&q=85\&s=00369add427dc4849f7a6f71ad8bb12d) Next, provide the access token via an environment variable [token](/docs/configuration/config-file#tokens) which is referenced in the `token` property: **Environment Variable** 1. Add the `token` property to your connection config: ```json theme={null} { "type": "gitea", "token": { // note: this env var can be named anything. It // doesn't need to be `GITEA_TOKEN`. "env": "GITEA_TOKEN" }, // At least one of the following is required to specify which repos to sync: "repos": ["my-org/myRepo"], // "orgs": ["my-org"], // "users": ["my-user"] } ``` 2. Pass this environment variable each time you run Sourcebot: ```bash theme={null} docker run \ -e GITEA_TOKEN= \ /* additional args */ \ docker.sourcebot.dev/sourcebot-dev/sourcebot:latest ``` ## Connecting to a custom Gitea To connect to a custom Gitea deployment, provide the `url` property to your config: ```json theme={null} { "type": "gitea", "url": "https://gitea.example.com", // At least one of the following is required to specify which repos to sync: "repos": ["my-org/myRepo"], // "orgs": ["my-org"], // "users": ["my-user"] } ``` ## Schema reference > **Reference** > > [schemas/v3/gitea.json](https://github.com/sourcebot-dev/sourcebot/blob/main/schemas/v3/gitea.json) > > ```json theme={null} > { > "$schema": "http://json-schema.org/draft-07/schema#", > "type": "object", > "title": "GiteaConnectionConfig", > "properties": { > "type": { > "const": "gitea", > "description": "Gitea Configuration" > }, > "token": { > "description": "A Personal Access Token (PAT).", > "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 > } > ] > }, > "url": { > "type": "string", > "format": "url", > "default": "https://gitea.com", > "description": "The URL of the Gitea host. Defaults to https://gitea.com", > "examples": [ > "https://gitea.com", > "https://gitea.example.com" > ], > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$" > }, > "orgs": { > "type": "array", > "items": { > "type": "string" > }, > "examples": [ > [ > "my-org-name" > ] > ], > "description": "List of organizations to sync with. All repositories in the organization visible to the provided `token` (if any) will be synced, unless explicitly defined in the `exclude` property. If a `token` is provided, it must have the read:organization scope." > }, > "repos": { > "type": "array", > "items": { > "type": "string", > "pattern": "^[\\w.-]+\\/[\\w.-]+$" > }, > "description": "List of individual repositories to sync with. Expected to be formatted as '{orgName}/{repoName}' or '{userName}/{repoName}'." > }, > "users": { > "type": "array", > "items": { > "type": "string" > }, > "examples": [ > [ > "username-1", > "username-2" > ] > ], > "description": "List of users to sync with. All repositories that the user owns will be synced, unless explicitly defined in the `exclude` property. If a `token` is provided, it must have the read:user scope." > }, > "exclude": { > "type": "object", > "properties": { > "forks": { > "type": "boolean", > "default": false, > "description": "Exclude forked repositories from syncing." > }, > "archived": { > "type": "boolean", > "default": false, > "description": "Exclude archived repositories from syncing." > }, > "repos": { > "type": "array", > "items": { > "type": "string" > }, > "default": [], > "description": "List of individual repositories to exclude from syncing. Glob patterns are supported." > } > }, > "additionalProperties": false > }, > "revisions": { > "type": "object", > "description": "The revisions (branches, tags) that should be included when indexing. The default branch (HEAD) is always indexed. A maximum of 64 revisions can be indexed, with any additional revisions being ignored.", > "properties": { > "branches": { > "type": "array", > "description": "List of branches to include when indexing. For a given repo, only the branches that exist on the repo's remote *and* match at least one of the provided `branches` will be indexed. The default branch (HEAD) is always indexed. Glob patterns are supported. A maximum of 64 branches can be indexed, with any additional branches being ignored.", > "items": { > "type": "string" > }, > "examples": [ > [ > "main", > "release/*" > ], > [ > "**" > ] > ], > "default": [] > }, > "tags": { > "type": "array", > "description": "List of tags to include when indexing. For a given repo, only the tags that exist on the repo's remote *and* match at least one of the provided `tags` will be indexed. Glob patterns are supported. A maximum of 64 tags can be indexed, with any additional tags being ignored.", > "items": { > "type": "string" > }, > "examples": [ > [ > "latest", > "v2.*.*" > ], > [ > "**" > ] > ], > "default": [] > } > }, > "additionalProperties": false > }, > "enforcePermissions": { > "type": "boolean", > "description": "Controls whether repository permissions are enforced for this connection. When `PERMISSION_SYNC_ENABLED` is false, this setting has no effect. Defaults to the value of `PERMISSION_SYNC_ENABLED`. See https://docs.sourcebot.dev/docs/features/permission-syncing" > }, > "enforcePermissionsForPublicRepos": { > "type": "boolean", > "default": false, > "description": "Controls whether repository permissions are enforced for public repositories in this connection. When true, public repositories are only visible to users with a linked account for this connection's code host. When false, public repositories are visible to all users. Has no effect when enforcePermissions is false. Defaults to false. See https://docs.sourcebot.dev/docs/features/permission-syncing" > } > }, > "required": [ > "type" > ], > "additionalProperties": false > } > ``` # Linking code from GitHub Source: https://docs.sourcebot.dev/docs/connections/github Sourcebot can sync code from GitHub.com, GitHub Enterprise Server, and GitHub Enterprise Cloud. If you're not familiar with Sourcebot [connections](/docs/connections/indexing-your-code), please read that overview first. ## Examples > **Sync individual repos** > > ```json theme={null} > { > "type": "github", > "repos": [ > "sourcebot-dev/sourcebot", > "getsentry/sentry", > "torvalds/linux" > ] > } > ``` > **Sync all repos in a organization** > > ```json theme={null} > { > "type": "github", > "orgs": [ > "sourcebot-dev", > "getsentry", > "vercel" > ] > } > ``` > **Sync all repos owned by a user** > > ```json theme={null} > { > "type": "github", > "users": [ > "torvalds", > "ggerganov" > ] > } > ``` > **Filter repos by topic** > > ```json theme={null} > { > "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" > ] > } > > ``` > **Exclude repos from syncing** > > ```json theme={null} > { > "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" > ] > } > } > ``` ## Authenticating with GitHub In order to index private repositories, you'll need to authenticate with GitHub. Sourcebot supports the following mechanisms of authenticating a GitHub connection: > **GitHub App** > > **1. 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/auth/sso#github) > > **2. 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.** > > **3. 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. > > **4. 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" theme={null} > "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 > } > } > ] > ``` > > **5. You're done!** > > That's it! Sourcebot will now use this GitHub App to authenticate when pulling repos for this connection. > **Fine-grained personal access tokens** > > **1. 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](https://mintcdn.com/sourcebot/8vfJfQmq9Ve6HNrE/images/github_pat_scopes_fine_grained.png?fit=max\&auto=format\&n=8vfJfQmq9Ve6HNrE\&q=85\&s=3e065e4a2127ba099b6a76faea10bc9f) > > [GitHub docs](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#fine-grained-personal-access-tokens) > > **2. 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/indexing-your-code) config object. > > The most common mechanism of doing this is defining an environment variable that holds the PAT: > > ```json theme={null} > { > "type": "github", > "token": { > // note: this env var can be named anything. It > // doesn't need to be `GITHUB_TOKEN`. > "env": "GITHUB_TOKEN" > }, > // At least one of the following is required to specify which repos to sync: > "repos": ["my-org/myRepo"], > // "orgs": ["my-org"], > // "users": ["my-user"] > } > ``` > > **3. You're done!** > > That's it! Sourcebot will now use this PAT to authenticate when pulling repos for this connection. > **Personal access tokens (classic)** > > **1. Create PAT** > > Create a new PAT [here](https://github.com/settings/tokens/new) and make sure you select the `repo` scope: > > ![GitHub PAT Scope](https://mintcdn.com/sourcebot/8vfJfQmq9Ve6HNrE/images/github_pat_scopes.png?fit=max\&auto=format\&n=8vfJfQmq9Ve6HNrE\&q=85\&s=34af37a92d5345a8cfbf3d61a7f74749) > > [GitHub docs](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#personal-access-tokens-classic) > > **2. 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/indexing-your-code) config object. > > The most common mechanism of doing this is defining an environment variable that holds the PAT: > > ```json theme={null} > { > "type": "github", > "token": { > // note: this env var can be named anything. It > // doesn't need to be `GITHUB_TOKEN`. > "env": "GITHUB_TOKEN" > }, > // At least one of the following is required to specify which repos to sync: > "repos": ["my-org/myRepo"], > // "orgs": ["my-org"], > // "users": ["my-user"] > } > ``` > > **3. You're done!** > > That's it! Sourcebot will now use this PAT to authenticate when pulling repos for this connection. ## Connecting to a custom GitHub host To connect to a GitHub host other than `github.com`, provide the `url` property to your config: ```json theme={null} { "type": "github", "url": "https://github.example.com", // At least one of the following is required to specify which repos to sync: "repos": ["my-org/myRepo"], // "orgs": ["my-org"], // "users": ["my-user"] } ``` ## Schema reference > **Reference** > > [schemas/v3/github.json](https://github.com/sourcebot-dev/sourcebot/blob/main/schemas/v3/github.json) > > ```json theme={null} > { > "$schema": "http://json-schema.org/draft-07/schema#", > "type": "object", > "title": "GithubConnectionConfig", > "properties": { > "type": { > "const": "github", > "description": "GitHub Configuration" > }, > "token": { > "description": "A Personal Access Token (PAT).", > "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 > } > ] > }, > "url": { > "type": "string", > "format": "url", > "default": "https://github.com", > "description": "The URL of the GitHub host. Defaults to https://github.com", > "examples": [ > "https://github.com", > "https://github.example.com" > ], > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$" > }, > "users": { > "type": "array", > "items": { > "type": "string", > "pattern": "^[\\w.-]+$" > }, > "default": [], > "examples": [ > [ > "torvalds", > "DHH" > ] > ], > "description": "List of users to sync with. All repositories that the user owns will be synced, unless explicitly defined in the `exclude` property." > }, > "orgs": { > "type": "array", > "items": { > "type": "string", > "pattern": "^[\\w.-]+$" > }, > "default": [], > "examples": [ > [ > "my-org-name" > ], > [ > "sourcebot-dev", > "commaai" > ] > ], > "description": "List of organizations to sync with. All repositories in the organization visible to the provided `token` (if any) will be synced, unless explicitly defined in the `exclude` property." > }, > "repos": { > "type": "array", > "items": { > "type": "string", > "pattern": "^[\\w.-]+\\/[\\w.-]+$" > }, > "default": [], > "description": "List of individual repositories to sync with. Expected to be formatted as '{orgName}/{repoName}' or '{userName}/{repoName}'." > }, > "topics": { > "type": "array", > "items": { > "type": "string" > }, > "minItems": 1, > "default": [], > "description": "List of repository topics to include when syncing. Only repositories that match at least one of the provided `topics` will be synced. If not specified, all repositories will be synced, unless explicitly defined in the `exclude` property. Glob patterns are supported.", > "examples": [ > [ > "docs", > "core" > ] > ] > }, > "exclude": { > "type": "object", > "properties": { > "forks": { > "type": "boolean", > "default": false, > "description": "Exclude forked repositories from syncing." > }, > "archived": { > "type": "boolean", > "default": false, > "description": "Exclude archived repositories from syncing." > }, > "private": { > "type": "boolean", > "default": false, > "description": "Exclude private repositories from syncing. Internal repositories are not affected." > }, > "repos": { > "type": "array", > "items": { > "type": "string" > }, > "default": [], > "description": "List of individual repositories to exclude from syncing. Glob patterns are supported." > }, > "topics": { > "type": "array", > "items": { > "type": "string" > }, > "default": [], > "description": "List of repository topics to exclude when syncing. Repositories that match one of the provided `topics` will be excluded from syncing. Glob patterns are supported.", > "examples": [ > [ > "tests", > "ci" > ] > ] > }, > "size": { > "type": "object", > "description": "Exclude repositories based on their disk usage. Note: the disk usage is calculated by GitHub and may not reflect the actual disk usage when cloned.", > "properties": { > "min": { > "type": "integer", > "description": "Minimum repository size (in bytes) to sync (inclusive). Repositories less than this size will be excluded from syncing." > }, > "max": { > "type": "integer", > "description": "Maximum repository size (in bytes) to sync (inclusive). Repositories greater than this size will be excluded from syncing." > } > }, > "additionalProperties": false > } > }, > "additionalProperties": false > }, > "revisions": { > "type": "object", > "description": "The revisions (branches, tags) that should be included when indexing. The default branch (HEAD) is always indexed. A maximum of 64 revisions can be indexed, with any additional revisions being ignored.", > "properties": { > "branches": { > "type": "array", > "description": "List of branches to include when indexing. For a given repo, only the branches that exist on the repo's remote *and* match at least one of the provided `branches` will be indexed. The default branch (HEAD) is always indexed. Glob patterns are supported. A maximum of 64 branches can be indexed, with any additional branches being ignored.", > "items": { > "type": "string" > }, > "examples": [ > [ > "main", > "release/*" > ], > [ > "**" > ] > ], > "default": [] > }, > "tags": { > "type": "array", > "description": "List of tags to include when indexing. For a given repo, only the tags that exist on the repo's remote *and* match at least one of the provided `tags` will be indexed. Glob patterns are supported. A maximum of 64 tags can be indexed, with any additional tags being ignored.", > "items": { > "type": "string" > }, > "examples": [ > [ > "latest", > "v2.*.*" > ], > [ > "**" > ] > ], > "default": [] > } > }, > "additionalProperties": false > }, > "enforcePermissions": { > "type": "boolean", > "description": "Controls whether repository permissions are enforced for this connection. When `PERMISSION_SYNC_ENABLED` is false, this setting has no effect. Defaults to the value of `PERMISSION_SYNC_ENABLED`. See https://docs.sourcebot.dev/docs/features/permission-syncing" > }, > "enforcePermissionsForPublicRepos": { > "type": "boolean", > "default": false, > "description": "Controls whether repository permissions are enforced for public repositories in this connection. When true, public repositories are only visible to users with a linked account for this connection's code host. When false, public repositories are visible to all users. Has no effect when enforcePermissions is false. Defaults to false. See https://docs.sourcebot.dev/docs/features/permission-syncing" > } > }, > "required": [ > "type" > ], > "additionalProperties": false > } > ``` ## See also * [Syncing GitHub Access permissions to Sourcebot](/docs/features/permission-syncing#github) # Linking code from GitLab Source: https://docs.sourcebot.dev/docs/connections/gitlab Sourcebot can sync code from GitLab.com, Self Managed (CE & EE), and Dedicated. If you're not familiar with Sourcebot [connections](/docs/connections/indexing-your-code), please read that overview first. ## Examples > **Sync individual projects** > > ```json theme={null} > { > "type": "gitlab", > "projects": [ > "my-group/foo", > "my-group/subgroup/bar" > ] > } > ``` > **Sync all projects in a group/subgroup** > > ```json theme={null} > { > "type": "gitlab", > "groups": [ > "my-group", > "my-other-group/sub-group" > ] > } > ``` > **Sync all projects in a self managed instance** > > > [!NOTE] > > > > This option is ignored if `url` is unset. See [connecting to a custom gitlab host](/docs/connections/gitlab#connecting-to-a-custom-gitlab-host). > > ```json theme={null} > { > "type": "gitlab", > "url": "https://gitlab.example.com", > // Index all projects in this self-managed instance > "all": true > } > ``` > **Sync all projects owned by a user** > > ```json theme={null} > { > "type": "gitlab", > "users": [ > "user-1", > "user-2" > ] > } > ``` > **Filter projects by topic** > > ```json theme={null} > { > "type": "gitlab", > // Sync all projects in `my-group` that have a topic that... > "groups": [ > "my-group" > ], > // ...match one of these glob patterns. > "topics": [ > "test-*", > "ci-*", > "k8s" > ] > } > > ``` > **Exclude projects from syncing** > > ```json theme={null} > { > "type": "gitlab", > // Include all projects in these groups... > "groups": [ > "my-group", > "my-other-group/sub-group" > ] > // ...except: > "exclude": { > // projects that are archived > "archived": true, > // projects that are forks > "forks": true, > // projects that are owned by users (not groups) > "userOwnedProjects": true, > // projects that match these glob patterns > "projects": [ > "my-group/foo/**", > "my-group/bar/**", > "my-other-group/sub-group/specific-project" > ], > // repos with topics that match these glob patterns > "topics": [ > "test-*", > "ci" > ] > } > } > ``` ## Authenticating with GitLab In order to index private projects, you'll need to generate a GitLab Personal Access Token (PAT). Create a new PAT [here](https://gitlab.com/-/user_settings/personal_access_tokens) and make sure you select the `read_api` scope: ![GitLab PAT Scope](https://mintcdn.com/sourcebot/8vfJfQmq9Ve6HNrE/images/gitlab_pat_scopes.png?fit=max\&auto=format\&n=8vfJfQmq9Ve6HNrE\&q=85\&s=58f0b3c9e6f19860e35902e432f17761) Next, provide the PAT via an environment variable [token](/docs/configuration/config-file#tokens) which is referenced in the `token` property: **Environment Variable** 1. Add the `token` property to your connection config: ```json theme={null} { "type": "gitlab", "token": { // note: this env var can be named anything. It // doesn't need to be `GITLAB_TOKEN`. "env": "GITLAB_TOKEN" }, // At least one of the following is required to specify which projects to sync: "projects": ["my-group/myProject"], // "groups": ["my-group"], // "users": ["my-user"], // "all": true (self-managed only) } ``` 2. Pass this environment variable each time you run Sourcebot: ```bash theme={null} docker run \ -e GITLAB_TOKEN= \ /* additional args */ \ docker.sourcebot.dev/sourcebot-dev/sourcebot:latest ``` ## Connecting to a custom GitLab host To connect to a GitLab host other than `gitlab.com`, provide the `url` property to your config: ```json theme={null} { "type": "gitlab", "url": "https://gitlab.example.com", // At least one of the following is required to specify which projects to sync: "projects": ["my-group/myProject"], // "groups": ["my-group"], // "users": ["my-user"], // "all": true } ``` ## Troubleshooting * If you're seeing errors like `GitbeakerTimeoutError: Query timeout was reached` when syncing a large number of projects, you can increase the client's timeout by setting the `GITLAB_CLIENT_QUERY_TIMEOUT_SECONDS` environment variable. [#162](https://github.com/sourcebot-dev/sourcebot/issues/162) * If you're seeing errors like `TypeError: fetch failed` when fetching user/project info, it may be that Sourcebot is refusing to connect to your self-hosted GitLab instance due to unrecognized SSL certs. Try setting the `NODE_TLS_REJECT_UNAUTHORIZED=0` environment variable or providing Sourcebot your certs through the `NODE_EXTRA_CA_CERTS` environment variable. ## Schema reference > **Reference** > > [schemas/v3/gitlab.json](https://github.com/sourcebot-dev/sourcebot/blob/main/schemas/v3/gitlab.json) > > ```json theme={null} > { > "$schema": "http://json-schema.org/draft-07/schema#", > "type": "object", > "title": "GitlabConnectionConfig", > "properties": { > "type": { > "const": "gitlab", > "description": "GitLab Configuration" > }, > "token": { > "description": "An authentication token.", > "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 > } > ] > }, > "url": { > "type": "string", > "format": "url", > "default": "https://gitlab.com", > "description": "The URL of the GitLab host. Defaults to https://gitlab.com", > "examples": [ > "https://gitlab.com", > "https://gitlab.example.com" > ], > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$" > }, > "webUrl": { > "type": "string", > "format": "url", > "description": "The base URL used to construct links to repositories in the GitLab web UI. Useful when the API is served from a different host than the one users browse (e.g. `https://api.gitlab.example.com` for `url` and `https://gitlab.example.com` for `webUrl`). Defaults to the value of `url`.", > "examples": [ > "https://gitlab.example.com" > ], > "pattern": "^https?:\\/\\/[^\\s/$.?#].[^\\s]*$" > }, > "all": { > "type": "boolean", > "default": false, > "description": "Sync all projects visible to the provided `token` (if any) in the GitLab instance. This option is ignored if `url` is either unset or set to https://gitlab.com ." > }, > "users": { > "type": "array", > "items": { > "type": "string" > }, > "description": "List of users to sync with. All projects owned by the user and visible to the provided `token` (if any) will be synced, unless explicitly defined in the `exclude` property." > }, > "groups": { > "type": "array", > "items": { > "type": "string" > }, > "examples": [ > [ > "my-group" > ], > [ > "my-group/sub-group-a", > "my-group/sub-group-b" > ] > ], > "description": "List of groups to sync with. All projects in the group (and recursive subgroups) visible to the provided `token` (if any) will be synced, unless explicitly defined in the `exclude` property. Subgroups can be specified by providing the path to the subgroup (e.g. `my-group/sub-group-a`)." > }, > "projects": { > "type": "array", > "items": { > "type": "string" > }, > "examples": [ > [ > "my-group/my-project" > ], > [ > "my-group/my-sub-group/my-project" > ] > ], > "description": "List of individual projects to sync with. The project's namespace must be specified. See: https://docs.gitlab.com/ee/user/namespace/" > }, > "topics": { > "type": "array", > "items": { > "type": "string" > }, > "minItems": 1, > "description": "List of project topics to include when syncing. Only projects that match at least one of the provided `topics` will be synced. If not specified, all projects will be synced, unless explicitly defined in the `exclude` property. Glob patterns are supported.", > "examples": [ > [ > "docs", > "core" > ] > ] > }, > "exclude": { > "type": "object", > "properties": { > "forks": { > "type": "boolean", > "default": false, > "description": "Exclude forked projects from syncing." > }, > "archived": { > "type": "boolean", > "default": false, > "description": "Exclude archived projects from syncing." > }, > "userOwnedProjects": { > "type": "boolean", > "default": false, > "description": "Exclude user-owned projects from syncing." > }, > "projects": { > "type": "array", > "items": { > "type": "string" > }, > "default": [], > "examples": [ > [ > "my-group/my-project" > ] > ], > "description": "List of projects to exclude from syncing. Glob patterns are supported. The project's namespace must be specified, see: https://docs.gitlab.com/ee/user/namespace/" > }, > "topics": { > "type": "array", > "items": { > "type": "string" > }, > "description": "List of project topics to exclude when syncing. Projects that match one of the provided `topics` will be excluded from syncing. Glob patterns are supported.", > "examples": [ > [ > "tests", > "ci" > ] > ] > } > }, > "additionalProperties": false > }, > "revisions": { > "type": "object", > "description": "The revisions (branches, tags) that should be included when indexing. The default branch (HEAD) is always indexed. A maximum of 64 revisions can be indexed, with any additional revisions being ignored.", > "properties": { > "branches": { > "type": "array", > "description": "List of branches to include when indexing. For a given repo, only the branches that exist on the repo's remote *and* match at least one of the provided `branches` will be indexed. The default branch (HEAD) is always indexed. Glob patterns are supported. A maximum of 64 branches can be indexed, with any additional branches being ignored.", > "items": { > "type": "string" > }, > "examples": [ > [ > "main", > "release/*" > ], > [ > "**" > ] > ], > "default": [] > }, > "tags": { > "type": "array", > "description": "List of tags to include when indexing. For a given repo, only the tags that exist on the repo's remote *and* match at least one of the provided `tags` will be indexed. Glob patterns are supported. A maximum of 64 tags can be indexed, with any additional tags being ignored.", > "items": { > "type": "string" > }, > "examples": [ > [ > "latest", > "v2.*.*" > ], > [ > "**" > ] > ], > "default": [] > } > }, > "additionalProperties": false > }, > "enforcePermissions": { > "type": "boolean", > "description": "Controls whether repository permissions are enforced for this connection. When `PERMISSION_SYNC_ENABLED` is false, this setting has no effect. Defaults to the value of `PERMISSION_SYNC_ENABLED`. See https://docs.sourcebot.dev/docs/features/permission-syncing" > }, > "enforcePermissionsForPublicRepos": { > "type": "boolean", > "default": false, > "description": "Controls whether repository permissions are enforced for public repositories in this connection. When true, public repositories are only visible to users with a linked account for this connection's code host. When false, public repositories are visible to all users. Has no effect when enforcePermissions is false. Defaults to false. See https://docs.sourcebot.dev/docs/features/permission-syncing" > } > }, > "required": [ > "type" > ], > "additionalProperties": false > } > ``` # Indexing your code Source: https://docs.sourcebot.dev/docs/connections/indexing-your-code A **connection** represents Sourcebot's link to a code host platform (GitHub, GitLab, etc). Connections are defined within the [config file](/docs/configuration/config-file) you provide Sourcebot. Each connection defines how Sourcebot should authenticate and interact with a particular host, and which repositories to sync and index from that host. Connections are uniquely identified by their name. ```json wrap icon="code" Example config with two connections theme={null} { "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", "connections": { // 1. A connection to GitHub.com "github-connection": { "type": "github", "repos": [ "sourcebot-dev/sourcebot" ], "token": { "env": "GITHUB_TOKEN" } }, // 2. A connection to a self-hosted GitLab instance "gitlab-connection": { "type": "gitlab", "url": "https://gitlab.example.com", "groups": [ "my-group", "my-other-group/sub-group" ], "token": { "env": "GITLAB_TOKEN" } } } } ``` Configuration files must conform to the [JSON schema](#schema-reference). ## Connection Syncing When a connection is first discovered, or the `resyncConnectionIntervalMs` [setting](/docs/configuration/config-file#settings) has exceeded, the connection will be synced. This consists of: 1. Fetching the latest changes from `HEAD` (and any [additional branches](/docs/features/search/multi-branch-indexing)) from the code host. 2. Re-indexing the repository. This is processed in a [job queue](/docs/misc/architecture), and is parallelized across multiple worker processes. Jobs will take longer to complete the first time a repository is synced, or when a diff is large. On the home page, you can view the sync status of ongoing jobs: