# 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. This API is only available with an active Sourcebot license. [More information](/docs/activating-a-subscription). # 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. This API is only available with an active Sourcebot license. [More information](/docs/activating-a-subscription). # 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. This API is only available with an active Sourcebot license. [More information](/docs/activating-a-subscription). # 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. This API is only available with an active Sourcebot license. [More information](/docs/activating-a-subscription). # 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. # 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. # 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. # 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. # 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. # 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. # 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. # 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. # 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. # 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. # 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. ## Usage The `query` field supports literal, regexp, and symbol searches with filters for repository, file, language, branch, and more. See the [search syntax reference](https://docs.sourcebot.dev/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) 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 downgrade to the free plan until a successul 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) 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 free 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. If [anonymous access](/docs/configuration/auth/access-settings#anonymous-access) is enabled, some endpoints will be accessible without a API key. ## 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 ## 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}' ``` # Audit Logs Source: https://docs.sourcebot.dev/docs/configuration/audit-logs 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. ## Enabling/Disabling Audit Logs Audit logs are enabled by default and can be controlled with the `SOURCEBOT_EE_AUDIT_LOGGING_ENABLED` [environment variable](/docs/configuration/environment-variables). ## 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", "targetId": "205d1da1c6c3772b81d4ad697f5851fa11195176c211055ff0c1509772645d6d", "targetType": "api_key", "sourcebotVersion": "unknown", "orgId": 1 }, { "id": "cmc146c8r0001xgo2xyu0p463", "timestamp": "2025-06-17T22:47:58.587Z", "action": "user.performed_code_search", "actorId": "cmc12tnje0000xgn58jj8655h", "actorType": "user", "targetId": "1", "targetType": "org", "sourcebotVersion": "unknown", "metadata": { "message": "render branch:HEAD" }, "orgId": 1 }, { "id": "cmc12vqgb0008xgn5nv5hl9y5", "timestamp": "2025-06-17T22:11:44.171Z", "action": "user.performed_code_search", "actorId": "cmc12tnje0000xgn58jj8655h", "actorType": "user", "targetId": "1", "targetType": "org", "sourcebotVersion": "unknown", "metadata": { "message": "render branch:HEAD" }, "orgId": 1 }, { "id": "cmc12txwn0006xgn51ow1odid", "timestamp": "2025-06-17T22:10:20.519Z", "action": "user.performed_code_search", "actorId": "cmc12tnje0000xgn58jj8655h", "actorType": "user", "targetId": "1", "targetType": "org", "sourcebotVersion": "unknown", "metadata": { "message": "render branch:HEAD" }, "orgId": 1 }, { "id": "cmc12tnjx0004xgn5qqeiv1ao", "timestamp": "2025-06-17T22:10:07.101Z", "action": "user.owner_created", "actorId": "cmc12tnje0000xgn58jj8655h", "actorType": "user", "targetId": "1", "targetType": "org", "sourcebotVersion": "unknown", "metadata": null, "orgId": 1 }, { "id": "cmc12tnjh0002xgn5h6vzu3rl", "timestamp": "2025-06-17T22:10:07.086Z", "action": "user.signed_in", "actorId": "cmc12tnje0000xgn58jj8655h", "actorType": "user", "targetId": "cmc12tnje0000xgn58jj8655h", "targetType": "user", "sourcebotVersion": "unknown", "metadata": null, "orgId": 1 } ] ``` ## Audit action types | Action | Actor Type | Target Type | | :--------------------------------- | :--------- | :--------------------- | | `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` | | `chat.deleted` | `user` | `chat` | | `chat.shared_with_users` | `user` | `chat` | | `chat.unshared_with_user` | `user` | `chat` | | `chat.visibility_updated` | `user` | `chat` | | `user.created_ask_chat` | `user` | `org` | | `user.creation_failed` | `user` | `user` | | `user.delete` | `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_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.owner_created` | `user` | `org` | | `user.performed_code_search` | `user` | `org` | | `user.performed_find_references` | `user` | `org` | | `user.performed_goto_definition` | `user` | `org` | | `user.read` | `user` | `user` | | `user.signed_in` | `user` | `user` | | `user.signed_out` | `user` | `user` | | `org.member_promoted_to_owner` | `user` | `user` | | `org.owner_demoted_to_member` | `user` | `user` | | `org.member_added` | `user` | `user` | | `org.member_removed` | `user` | `user` | | `org.member_left` | `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", "targetId", "targetType", "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"] }, "targetId": { "type": "string" }, "targetType": { "type": "string", "enum": ["user", "org", "file", "api_key", "account_join_request", "invite", "chat"] }, "sourcebotVersion": { "type": "string" }, "metadata": { "anyOf": [ { "type": "object", "properties": { "message": { "type": "string" }, "api_key": { "type": "string" }, "emails": { "type": "string" }, "source": { "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 ### 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 # Anonymous access Anonymous access is only available in the free plan. If you have any questions about this restriction [reach out to us](https://www.sourcebot.dev/contact). By default, your Sourcebot deployment is gated with a login page. If you'd like users to access the deployment anonymously, you can enable anonymous access. This can be enabled by navigating to **Settings -> Access**. Enable anonymous access toggle in Settings → Access When accessing Sourcebot anonymously, a user's permissions are limited to that of the [Guest](/docs/configuration/auth/roles-and-permissions) role. # Authentication Source: https://docs.sourcebot.dev/docs/configuration/auth/authentication If you're deploying Sourcebot behind a domain, you must set the [AUTH\_URL](/docs/configuration/environment-variables) environment variable. Sourcebot's built-in authentication system gates your deployment, and allows administrators to manage users and their permissions. Configure additional authentication providers for your deployment. Learn how to configure how members join your deployment. Provision and deprovision organization members from your identity provider. Learn more about the different roles and permissions in Sourcebot. Have a question about Sourcebot's auth system? We might have the answers here. # 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. 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) 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. **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. 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/idp). If you're using a different IAP and require support, please [reach out](https://www.sourcebot.dev/contact) 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. # Providers Source: https://docs.sourcebot.dev/docs/configuration/auth/providers Sourcebot supports a wide range of different authentication providers through it's integration with [Auth.js](https://authjs.dev/). This page highlights how to configure the various supported providers. If there's an authentication provider you'd like us to support, please [reach out](https://www.sourcebot.dev/contact). # Core Authentication Providers ### Email / Password Email / password authentication is enabled by default. You can toggle it from **Settings → Security** using the **Email login** setting. Email & password login setting toggle in Settings → Security ### Email codes Email codes are 6 digit codes sent to a provided email. Email codes are enabled when [transactional emails](/docs/configuration/transactional-emails) and the **Email code** setting is toggled from **Settings → Security**: Email code login setting toggle in Settings → Security # Enterprise Authentication Providers Sourcebot supports authentication using several different [external identity providers](/docs/configuration/idp) as well. These identity providers require an [enterprise license](/docs/activating-a-subscription) # 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. | | `Guest` | Guests are users that access Sourcebot without a account when [anonymous access](/docs/configuration/auth/access-settings#anonymous-access) is enabled. Guests can use some features, such as code search and browsing files, with additional limitations like not having chat history. Guests **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**. On the free 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 | | :------- | :----------- | :------------------------------------------------------------------------- | | **Free** | `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 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 ### 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 ### 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 ### 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 # 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 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. 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 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/idp#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 ## 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 SCIM provisioning should work with most identity providers that support SCIM user provisioning, but it has only been tested with Okta. Sourcebot supports SCIM 2.0. 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. # 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: ```json theme={null} { "token": { "env": "TOKEN_NAME" } } ``` ```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. ```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" } } }, } ``` ```jsonc theme={null} { "environmentOverrides": { "EMAIL_FROM_ADDRESS": { "type": "string", "value": "hello@sourcebot.dev" } } } ``` ```jsonc theme={null} { "environmentOverrides": { "SOURCEBOT_CHAT_MODEL_TEMPERATURE": { "type": "number", "value": 0.5 } } } ``` ```jsonc theme={null} { "environmentOverrides": { "SOURCEBOT_TELEMETRY_DISABLED": { "type": "boolean", "value": false } } } ``` **Note:** Overrides are **not** set as system environment variables, and instead are resolved at runtime on startup and stored in memory. [schemas/v3/environmentOverrides.json](https://github.com/sourcebot-dev/sourcebot/blob/main/schemas/v3/environmentOverrides.json) ```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 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`.

| | `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

| | `SOURCEBOT_TELEMETRY_DISABLED` | `false` |

Enables/disables telemetry collection in Sourcebot. See [this doc](/docs/misc/telemetry) for more info.

| | `DEFAULT_MAX_MATCH_COUNT` | `10000` |

The default maximum number of search results to return when using search in the web app.

| | `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. Anonymous requests omit the 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_LOGGING_ENABLED` | `true` |

Enables/disables audit logging

| | `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. # External Identity Providers Source: https://docs.sourcebot.dev/docs/configuration/idp only available in a paid plan. Please activate a [license key](/docs/activating-a-subscription) to use this feature. You can connect Sourcebot to various **external identity providers** to associate a Sourcebot user with one or more external service accounts (ex. Google, GitHub, etc). External identity providers can be used for [authentication](/docs/configuration/auth) and/or [permission syncing](/docs/features/permission-syncing). They're defined in the [config file](/docs/configuration/config-file) in the top-level `identityProviders` array: ```json wrap icon="code" Example config with both google and github identity providers defined 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" } }, { "provider": "google", "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 External 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) and/or [permission syncing](/docs/features/permission-syncing). This is controlled using the `purpose` field in the GitHub identity provider config. 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. 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 Select "Request user authorization (OAuth) during installation" GitHub App request user authorization during installation Set the following fine-grained permissions in the GitHub App: * `“Email addresses” account permissions (read)` Email addresses account permission set to Read-only * `"Metadata" repository permissions (read)` (only needed if using [permission syncing](/docs/features/permission-syncing)) Metadata repository permission set to Read-only * `"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 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. 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`) 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", // "sso" for auth + perm sync, "account_linking" for only perm sync "purpose": "account_linking", // if purpose == "account_linking" this controls if a user must connect to the IdP "accountLinkingRequired": true, "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) and/or [permission syncing](/docs/features/permission-syncing). This is controlled using the `purpose` field in the GitLab identity provider config. 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. 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`) 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", // "sso" for auth + perm sync, "account_linking" for only perm sync "purpose": "account_linking", // if purpose == "account_linking" this controls if a user must connect to the IdP "accountLinkingRequired": true, "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) and/or [permission syncing](/docs/features/permission-syncing). This is controlled using the `purpose` field in the Bitbucket Cloud identity provider config. 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. 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`) 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", // "sso" for auth + perm sync, "account_linking" for only perm sync "purpose": "account_linking", // if purpose == "account_linking" this controls if a user must connect to the IdP "accountLinkingRequired": true, "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) and/or [permission syncing](/docs/features/permission-syncing). This is controlled using the `purpose` field in the Bitbucket Server identity provider config. 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. 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`) 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", // "sso" for auth + perm sync, "account_linking" for only perm sync "purpose": "account_linking", // if purpose == "account_linking" this controls if a user must connect to the IdP "accountLinkingRequired": true, "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). 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. 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`) 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). 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. 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`) 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). 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. 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`) 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" } } ] } ``` ### 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). 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. 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. 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` 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). 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//`). 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`) 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). JumpCloud supports OIDC (OpenID Connect), which Sourcebot uses to authenticate users. 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`. 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. 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). Sourcebot uses Idira's OpenID Connect support to authenticate users. 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. 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`). 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). IAP provides a layer of security for applications deployed on Google Cloud, allowing you to control access based on user identity and context. 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. 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/`. Set the IAP audience as an environment variable. This can be named whatever you like (ex. `GCP_IAP_AUDIENCE`). 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" } } ] } ``` # 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. Each instance needs its own OAuth client (its own `clientId` and `clientSecret`) registered with the matching callback URL. # Language Model Providers Source: https://docs.sourcebot.dev/docs/configuration/language-model-providers 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). 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" } ] } ``` ### 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 If you're using an Anthropic model on Google Vertex, you must define a [Google Vertex Anthropic](#google-vertex-anthropic) provider instead 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 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" } } } ] } ``` * 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 [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." }, "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." }, "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/providers#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. ## Examples ```json theme={null} { "type": "azuredevops", "deploymentType": "cloud", "repos": [ "organizationName/projectName/repoName", "organizationName/projectName/repoName2 ] } ``` ```json theme={null} { "type": "azuredevops", "deploymentType": "cloud", "orgs": [ "organizationName", "organizationName2 ] } ``` ```json theme={null} { "type": "azuredevops", "deploymentType": "cloud", "projects": [ "organizationName/projectName", "organizationName/projectName2" ] } ``` ```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: 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 [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 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 ] } ``` ```json theme={null} { "type": "azuredevops", "deploymentType": "server", "repos": [ "organizationName/projectName/repoName", "organizationName/projectName/repoName2 ] } ``` ```json theme={null} { "type": "azuredevops", "deploymentType": "server", "orgs": [ "collectionName", "collectionName2" ] } ``` ```json theme={null} { "type": "azuredevops", "deploymentType": "server", "projects": [ "collectionName/projectName", "collectionName/projectName2" ] } ``` ```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: 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 [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 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 ```json theme={null} { "type": "bitbucket", "deploymentType": "cloud", "repos": [ "myWorkspace/myRepo" ] } ``` ```json theme={null} { "type": "bitbucket", "deploymentType": "cloud", "workspaces": [ "myWorkspace" ] } ``` ```json theme={null} { "type": "bitbucket", "deploymentType": "cloud", "projects": [ "myProject" ] } ``` ```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`. 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 ``` 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 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 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 [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 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 ```json theme={null} { "type": "bitbucket", "deploymentType": "server", "url": "https://mybitbucketdeployment.com", "repos": [ "myProject/myRepo" ] } ``` ```json theme={null} { "type": "bitbucket", "deploymentType": "server", "url": "https://mybitbucketdeployment.com", "projects": [ "myProject" ] } ``` 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 } ``` ```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. 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 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 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 ## 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 [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 [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 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 ```json theme={null} { "type": "gerrit", "url": "https://gerrit.example.com", // Sync all repos under project1 and project2/sub-project "projects": [ "project1/**", "project2/sub-project/**" ] } ``` ```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 [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 ```json theme={null} { "type": "gitea", "repos": [ "sourcebot-dev/sourcebot", "getsentry/sentry", "torvalds/linux" ] } ``` ```json theme={null} { "type": "gitea", "orgs": [ "sourcebot-dev", "getsentry", "vercel" ] } ``` ```json theme={null} { "type": "gitea", "users": [ "torvalds", "ggerganov" ] } ``` ```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 Next, provide the access token via an environment variable [token](/docs/configuration/config-file#tokens) which is referenced in the `token` property: 1. Add the `token` property to your connection config: ```json 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 [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 ```json theme={null} { "type": "github", "repos": [ "sourcebot-dev/sourcebot", "getsentry/sentry", "torvalds/linux" ] } ``` ```json theme={null} { "type": "github", "orgs": [ "sourcebot-dev", "getsentry", "vercel" ] } ``` ```json theme={null} { "type": "github", "users": [ "torvalds", "ggerganov" ] } ``` ```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" ] } ``` ```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: only available in a paid plan. Please activate a [license key](/docs/activating-a-subscription) to use this feature. Register a new [GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app#registering-a-github-app) and provide it with the following permissions: * “Contents” repository permissions (read) * “Metadata” repository permissions (read) * “Members” organization permissions (read) * “Email addresses” account permissions (read) This can be the same GitHub App you've registered and configured as an [external identity provider](/docs/configuration/idp#github) Install the GitHub App into the GitHub orgs that you want Sourcebot to be aware of. **Sourcebot will only be able to index repos from orgs with the GitHub App installed.** Create a [private key](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps) for the GitHub App. Create a new `apps` object in the Sourcebot [config file](/docs/configuration/config-file). The private key you created in the previous step must be passed in as a [token](/docs/configuration/config-file#tokens). ```json wrap icon="code" 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 } } ] ``` That's it! Sourcebot will now use this GitHub App to authenticate when pulling repos for this connection. Create a new fine-grained PAT [here](https://github.com/settings/personal-access-tokens/new). 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 [GitHub docs](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#fine-grained-personal-access-tokens) Next, provide the PAT via a [token](/docs/configuration/config-file#tokens) which is referenced in the `token` field in the [connection](/docs/connections/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"] } ``` That's it! Sourcebot will now use this PAT to authenticate when pulling repos for this connection. Create a new PAT [here](https://github.com/settings/tokens/new) and make sure you select the `repo` scope: GitHub PAT Scope [GitHub docs](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#personal-access-tokens-classic) Next, provide the PAT via a [token](/docs/configuration/config-file#tokens) which is referenced in the `token` field in the [connection](/docs/connections/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"] } ``` 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 [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." }, "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 ```json theme={null} { "type": "gitlab", "projects": [ "my-group/foo", "my-group/subgroup/bar" ] } ``` ```json theme={null} { "type": "gitlab", "groups": [ "my-group", "my-other-group/sub-group" ] } ``` 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 } ``` ```json theme={null} { "type": "gitlab", "users": [ "user-1", "user-2" ] } ``` ```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" ] } ``` ```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 Next, provide the PAT via an environment variable [token](/docs/configuration/config-file#tokens) which is referenced in the `token` property: 1. Add the `token` property to your connection config: ```json 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 [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: