diff --git a/.github/workflows/changelog-reminder.yml b/.github/workflows/changelog-reminder.yml new file mode 100644 index 00000000..afb68c38 --- /dev/null +++ b/.github/workflows/changelog-reminder.yml @@ -0,0 +1,17 @@ +name: Changelog Reminder + +on: + pull_request: + types: [opened, synchronize, reopened, ready_for_review] + +jobs: + remind: + name: Changelog Reminder + runs-on: ubuntu-latest + if: ${{ !github.event.pull_request.draft }} + permissions: + contents: read + pull-requests: write + steps: + - uses: actions/checkout@v4 + - uses: mskelton/changelog-reminder-action@v3 \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index a121f0de..f1248604 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,8 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Changed +- Fixed typos in UI, docs, code [#369](https://github.com/sourcebot-dev/sourcebot/pull/369) + +## [4.5.1] - 2025-07-14 + +### Changed +- Revamped onboarding experience. [#376](https://github.com/sourcebot-dev/sourcebot/pull/376) + ### Fixed - Fixed issue with external source code links being broken for paths with spaces. [#364](https://github.com/sourcebot-dev/sourcebot/pull/364) +- Makes base retry indexing configuration configurable and move from a default of `5s` to `60s`. [#377](https://github.com/sourcebot-dev/sourcebot/pull/377) +- Fixed issue where files would sometimes never load in the code browser. [#365](https://github.com/sourcebot-dev/sourcebot/pull/365) ## [4.5.0] - 2025-06-21 @@ -229,7 +239,7 @@ Sourcebot v3 is here and brings a number of structural changes to the tool's fou ### Added -- Added `maxTrigramCount` to the config to control the maximum allowable of trigrams per document. +- Added `maxTrigramCount` to the config to control the maximum allowable of trigrams per document. ### Fixed @@ -287,7 +297,7 @@ Sourcebot v3 is here and brings a number of structural changes to the tool's fou - Added config option `settings.maxFileSize` to control the maximum file size zoekt will index. ([#118](https://github.com/sourcebot-dev/sourcebot/pull/118)) ### Fixed - + - Fixed syntax highlighting for zoekt query language. ([#115](https://github.com/sourcebot-dev/sourcebot/pull/115)) - Fixed issue with Gerrit repo fetching not paginating. ([#114](https://github.com/sourcebot-dev/sourcebot/pull/114)) - Fixed visual issues with filter panel. ([#105](https://github.com/sourcebot-dev/sourcebot/pull/105)) @@ -339,13 +349,13 @@ Sourcebot v3 is here and brings a number of structural changes to the tool's fou ### Added - Added `DOMAIN_SUB_PATH` environment variable to allow overriding the default domain subpath. ([#74](https://github.com/sourcebot-dev/sourcebot/pull/74)) -- Added option `all` to the GitLab index schema, allowing for indexing all projects in a self-hosted GitLab instance. ([#84](https://github.com/sourcebot-dev/sourcebot/pull/84)) +- Added option `all` to the GitLab index schema, allowing for indexing all projects in a self-hosted GitLab instance. ([#84](https://github.com/sourcebot-dev/sourcebot/pull/84)) ## [2.4.3] - 2024-11-18 ### Changed -- Bumped NodeJS version to v20. ([#78](https://github.com/sourcebot-dev/sourcebot/pull/78)) +- Bumped NodeJS version to v20. ([#78](https://github.com/sourcebot-dev/sourcebot/pull/78)) ## [2.4.2] - 2024-11-14 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3016d9d8..ae301793 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,7 +38,7 @@ 6. Create a copy of `.env.development` and name it `.env.development.local`. Update the required environment variables. -7. If you're using a declerative configuration file, create a configuration file and update the `CONFIG_PATH` environment variable in your `.env.development.local` file. +7. If you're using a declarative configuration file, create a configuration file and update the `CONFIG_PATH` environment variable in your `.env.development.local` file. 8. Start Sourcebot with the command: ```sh diff --git a/Makefile b/Makefile index 7af1fbb3..538a4e5d 100644 --- a/Makefile +++ b/Makefile @@ -10,7 +10,7 @@ yarn: zoekt: mkdir -p bin go build -C vendor/zoekt -o $(PWD)/bin ./cmd/... - export PATH=$(PWD)/bin:$(PATH) + export PATH="$(PWD)/bin:$(PATH)" export CTAGS_COMMANDS=ctags clean: diff --git a/_typos.toml b/_typos.toml new file mode 100644 index 00000000..fcf2868b --- /dev/null +++ b/_typos.toml @@ -0,0 +1,6 @@ +[default.extend-words] +# Don't correct the surname "Do Not Exists" +dne = "dne" + +[files] +extend-exclude = ["vendor/**/*", "CHANGELOG.md", "packages/web/src/lib/languageMetadata.ts"] diff --git a/docs/docs.json b/docs/docs.json index c8b3888e..3af230d7 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -52,7 +52,7 @@ "group": "Configuration", "pages": [ { - "group": "Connecting your code", + "group": "Indexing your code", "pages": [ "docs/connections/overview", "docs/connections/github", @@ -72,7 +72,10 @@ "group": "Authentication", "pages": [ "docs/configuration/auth/overview", - "docs/configuration/auth/roles-and-permissions" + "docs/configuration/auth/providers", + "docs/configuration/auth/inviting-members", + "docs/configuration/auth/roles-and-permissions", + "docs/configuration/auth/faq" ] }, "docs/configuration/transactional-emails", diff --git a/docs/docs/configuration/audit-logs.mdx b/docs/docs/configuration/audit-logs.mdx index 2a3c0624..f229caaf 100644 --- a/docs/docs/configuration/audit-logs.mdx +++ b/docs/docs/configuration/audit-logs.mdx @@ -125,7 +125,6 @@ curl --request GET '$SOURCEBOT_URL/api/ee/audit' \ | `user.join_requested` | `user` | `org` | | `user.join_request_approve_failed` | `user` | `account_join_request` | | `user.join_request_approved` | `user` | `account_join_request` | -| `user.join_request_removed` | `user` | `account_join_request` | | `user.invite_failed` | `user` | `org` | | `user.invites_created` | `user` | `org` | | `user.invite_accept_failed` | `user` | `invite` | diff --git a/docs/docs/configuration/auth/faq.mdx b/docs/docs/configuration/auth/faq.mdx new file mode 100644 index 00000000..5d37bc66 --- /dev/null +++ b/docs/docs/configuration/auth/faq.mdx @@ -0,0 +1,46 @@ +--- +title: 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 dosn'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/auth/providers#gcp-iap). 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 + (credientials, 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 it on our [GitHub discussions](https://github.com/sourcebot-dev/sourcebot/discussions) +page and we'll get back to you as soon as we can! \ No newline at end of file diff --git a/docs/docs/configuration/auth/inviting-members.mdx b/docs/docs/configuration/auth/inviting-members.mdx new file mode 100644 index 00000000..d67e497b --- /dev/null +++ b/docs/docs/configuration/auth/inviting-members.mdx @@ -0,0 +1,30 @@ +--- +title: Inviting Members +sidebarTitle: Inviting members +--- + +There are various ways to configure how members can join a Sourcebot deployment. + +## Member Approval + +**By default, Sourcebot requires new members to be approved by the owner of the deployment**. This section explains how approvals work and how +to configure this behavior. + +### Configuration +Member approval can be configured by the owner of the deployment by navigating to **Settings -> Members**: + +![Member Approval Toggle](/images/member_approval_toggle.png) + +### 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 the owner. + +The owner 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: + +![Invite Link Toggle](/images/invite_link_toggle.png) \ No newline at end of file diff --git a/docs/docs/configuration/auth/overview.mdx b/docs/docs/configuration/auth/overview.mdx index 3b11a4a9..732fef35 100644 --- a/docs/docs/configuration/auth/overview.mdx +++ b/docs/docs/configuration/auth/overview.mdx @@ -4,124 +4,23 @@ title: Overview If you're deploying Sourcebot behind a domain, you must set the [AUTH_URL](/docs/configuration/environment-variables) environment variable. -Sourcebot has built-in authentication that gates access to your organization. OAuth, email codes, and email / password are supported. +Sourcebot's built-in authentication system gates your deployment, and allows administrators to manage users and their permissions. -The first account that's registered on a Sourcebot deployment is made the owner. All other users who register must be [approved](/docs/configuration/auth/overview#approving-new-members) by the owner. + + + Configure additional authentication providers for your deployment. + + + Learn how to configure how members join your deployment. + + + Learn more about the different roles and permissions in Sourcebot. + + + Have a question about Sourcebot's auth system? We might have the answers here. + + -![Login Page](/images/login.png) - - -# Approving New Members - -All account registrations after the first account must be approved by the owner. The owner can see all join requests by going into **Settings -> Members**. - -If you have an [enterprise license](/docs/license-key), you can enable [AUTH_EE_ENABLE_JIT_PROVISIONING](/docs/configuration/auth/overview#enterprise-authentication-providers) to -have Sourcebot accounts automatically created and approved on registration. - -You can setup emails to be sent when new join requests are created/approved by configurating [transactional emails](/docs/configuration/transactional-emails) -# Authentication Providers - -To enable an authentication provider in Sourcebot, configure the required environment variables for the provider. Under the hood, Sourcebot uses Auth.js which supports [many providers](https://authjs.dev/getting-started/authentication/oauth). Submit a [feature request on GitHub](https://github.com/sourcebot-dev/sourcebot/discussions/categories/ideas) if you want us to add support for a specific provider. - -## Core Authentication Providers - -### Email / Password ---- -Email / password authentication is enabled by default. It can be **disabled** by setting `AUTH_CREDENTIALS_LOGIN_ENABLED` to `false`. - -### Email codes ---- -Email codes are 6 digit codes sent to a provided email. Email codes are enabled when transactional emails are configured using the following environment variables: - -- `AUTH_EMAIL_CODE_LOGIN_ENABLED` -- `SMTP_CONNECTION_URL` -- `EMAIL_FROM_ADDRESS` - - -See [transactional emails](/docs/configuration/transactional-emails) for more details. - -## Enterprise Authentication Providers - -The following authentication providers require an [enterprise license](/docs/license-key) to be enabled. - -By default, a new user registering using these providers must have their join request accepted by the owner of the organization to join. To allow a user to join automatically when -they register for the first time, set the `AUTH_EE_ENABLE_JIT_PROVISIONING` environment variable to `true`. - -### GitHub ---- - -[Auth.js GitHub Provider Docs](https://authjs.dev/getting-started/providers/github) - -**Required environment variables:** -- `AUTH_EE_GITHUB_CLIENT_ID` -- `AUTH_EE_GITHUB_CLIENT_SECRET` - -Optional environment variables: -- `AUTH_EE_GITHUB_BASE_URL` - Base URL for GitHub Enterprise (defaults to https://github.com) - -### GitLab ---- - -[Auth.js GitLab Provider Docs](https://authjs.dev/getting-started/providers/gitlab) - -**Required environment variables:** -- `AUTH_EE_GITLAB_CLIENT_ID` -- `AUTH_EE_GITLAB_CLIENT_SECRET` - -Optional environment variables: -- `AUTH_EE_GITLAB_BASE_URL` - Base URL for GitLab instance (defaults to https://gitlab.com) - -### Google ---- - -[Auth.js Google Provider Docs](https://authjs.dev/getting-started/providers/google) - -**Required environment variables:** -- `AUTH_EE_GOOGLE_CLIENT_ID` -- `AUTH_EE_GOOGLE_CLIENT_SECRET` - -### GCP IAP ---- - -If you're running Sourcebot in an environment that blocks egress, make sure you allow the [IAP IP ranges](https://www.gstatic.com/ipranges/goog.json) - -Custom provider built to enable automatic Sourcebot account registration/login when using GCP IAP. - -**Required environment variables** -- `AUTH_EE_GCP_IAP_ENABLED` -- `AUTH_EE_GCP_IAP_AUDIENCE` - - This can be found by selecting the ⋮ icon next to the IAP-enabled backend service and pressing `Get JWT audience code` - -### Okta ---- - -[Auth.js Okta Provider Docs](https://authjs.dev/getting-started/providers/okta) - -**Required environment variables:** -- `AUTH_EE_OKTA_CLIENT_ID` -- `AUTH_EE_OKTA_CLIENT_SECRET` -- `AUTH_EE_OKTA_ISSUER` - -### Keycloak ---- - -[Auth.js Keycloak Provider Docs](https://authjs.dev/getting-started/providers/keycloak) - -**Required environment variables:** -- `AUTH_EE_KEYCLOAK_CLIENT_ID` -- `AUTH_EE_KEYCLOAK_CLIENT_SECRET` -- `AUTH_EE_KEYCLOAK_ISSUER` - -### Microsoft Entra ID - -[Auth.js Microsoft Entra ID Provider Docs](https://authjs.dev/getting-started/providers/microsoft-entra-id) - -**Required environment variables:** -- `AUTH_EE_MICROSOFT_ENTRA_ID_CLIENT_ID` -- `AUTH_EE_MICROSOFT_ENTRA_ID_CLIENT_SECRET` -- `AUTH_EE_MICROSOFT_ENTRA_ID_ISSUER` - ---- # Troubleshooting diff --git a/docs/docs/configuration/auth/providers.mdx b/docs/docs/configuration/auth/providers.mdx new file mode 100644 index 00000000..ae52ea46 --- /dev/null +++ b/docs/docs/configuration/auth/providers.mdx @@ -0,0 +1,105 @@ +--- +title: 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 theres 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. It can be **disabled** by setting `AUTH_CREDENTIALS_LOGIN_ENABLED` to `false`. + +### Email codes +--- +Email codes are 6 digit codes sent to a provided email. Email codes are enabled when transactional emails are configured using the following environment variables: + +- `AUTH_EMAIL_CODE_LOGIN_ENABLED` +- `SMTP_CONNECTION_URL` +- `EMAIL_FROM_ADDRESS` + + +See [transactional emails](/docs/configuration/transactional-emails) for more details. + +# Enterprise Authentication Providers + +The following authentication providers require an [enterprise license](/docs/license-key) to be enabled. + +### GitHub +--- + +[Auth.js GitHub Provider Docs](https://authjs.dev/getting-started/providers/github) + +**Required environment variables:** +- `AUTH_EE_GITHUB_CLIENT_ID` +- `AUTH_EE_GITHUB_CLIENT_SECRET` + +Optional environment variables: +- `AUTH_EE_GITHUB_BASE_URL` - Base URL for GitHub Enterprise (defaults to https://github.com) + +### GitLab +--- + +[Auth.js GitLab Provider Docs](https://authjs.dev/getting-started/providers/gitlab) + +**Required environment variables:** +- `AUTH_EE_GITLAB_CLIENT_ID` +- `AUTH_EE_GITLAB_CLIENT_SECRET` + +Optional environment variables: +- `AUTH_EE_GITLAB_BASE_URL` - Base URL for GitLab instance (defaults to https://gitlab.com) + +### Google +--- + +[Auth.js Google Provider Docs](https://authjs.dev/getting-started/providers/google) + +**Required environment variables:** +- `AUTH_EE_GOOGLE_CLIENT_ID` +- `AUTH_EE_GOOGLE_CLIENT_SECRET` + +### GCP IAP +--- + +If you're running Sourcebot in an environment that blocks egress, make sure you allow the [IAP IP ranges](https://www.gstatic.com/ipranges/goog.json) + +Custom provider built to enable automatic Sourcebot account registration/login when using GCP IAP. + +**Required environment variables** +- `AUTH_EE_GCP_IAP_ENABLED` +- `AUTH_EE_GCP_IAP_AUDIENCE` + - This can be found by selecting the ⋮ icon next to the IAP-enabled backend service and pressing `Get JWT audience code` + +### Okta +--- + +[Auth.js Okta Provider Docs](https://authjs.dev/getting-started/providers/okta) + +**Required environment variables:** +- `AUTH_EE_OKTA_CLIENT_ID` +- `AUTH_EE_OKTA_CLIENT_SECRET` +- `AUTH_EE_OKTA_ISSUER` + +### Keycloak +--- + +[Auth.js Keycloak Provider Docs](https://authjs.dev/getting-started/providers/keycloak) + +**Required environment variables:** +- `AUTH_EE_KEYCLOAK_CLIENT_ID` +- `AUTH_EE_KEYCLOAK_CLIENT_SECRET` +- `AUTH_EE_KEYCLOAK_ISSUER` + +### Microsoft Entra ID + +[Auth.js Microsoft Entra ID Provider Docs](https://authjs.dev/getting-started/providers/microsoft-entra-id) + +**Required environment variables:** +- `AUTH_EE_MICROSOFT_ENTRA_ID_CLIENT_ID` +- `AUTH_EE_MICROSOFT_ENTRA_ID_CLIENT_SECRET` +- `AUTH_EE_MICROSOFT_ENTRA_ID_ISSUER` + +--- \ No newline at end of file diff --git a/docs/docs/configuration/environment-variables.mdx b/docs/docs/configuration/environment-variables.mdx index a55d735d..9378b023 100644 --- a/docs/docs/configuration/environment-variables.mdx +++ b/docs/docs/configuration/environment-variables.mdx @@ -25,6 +25,7 @@ The following environment variables allow you to configure your Sourcebot deploy | `REDIS_URL` | `redis://localhost:6379` |

Connection string of your Redis instance. By default, a Redis database is automatically provisioned at startup within the container.

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

| | `SHARD_MAX_MATCH_COUNT` | `10000` |

The maximum shard count per query

| | `SMTP_CONNECTION_URL` | `-` |

The url to the SMTP service used for sending transactional emails. See [this doc](/docs/configuration/transactional-emails) for more info.

| | `SOURCEBOT_ENCRYPTION_KEY` | Automatically generated at startup if no value is provided. Generated using `openssl rand -base64 24` |

Used to encrypt connection secrets and generate API keys.

| @@ -40,7 +41,6 @@ The following environment variables allow you to configure your Sourcebot deploy | Variable | Default | Description | | :------- | :------ | :---------- | | `SOURCEBOT_EE_AUDIT_LOGGING_ENABLED` | `true` |

Enables/disables audit logging

| -| `AUTH_EE_ENABLE_JIT_PROVISIONING` | `false` |

Enables/disables just-in-time user provisioning for SSO providers.

| | `AUTH_EE_GITHUB_BASE_URL` | `https://github.com` |

The base URL for GitHub Enterprise SSO authentication.

| | `AUTH_EE_GITHUB_CLIENT_ID` | `-` |

The client ID for GitHub Enterprise SSO authentication.

| | `AUTH_EE_GITHUB_CLIENT_SECRET` | `-` |

The client secret for GitHub Enterprise SSO authentication.

| diff --git a/docs/docs/connections/github.mdx b/docs/docs/connections/github.mdx index 2a86cecc..2f31994e 100644 --- a/docs/docs/connections/github.mdx +++ b/docs/docs/connections/github.mdx @@ -104,11 +104,29 @@ Sourcebot can sync code from GitHub.com, GitHub Enterprise Server, and GitHub En ## Authenticating with GitHub -In order to index private repositories, you'll need to generate a GitHub Personal Access Token (PAT). Create a new PAT [here](https://github.com/settings/tokens/new) and make sure you select the `repo` scope: +In order to index private repositories, you'll need to generate a access token and provide it to Sourcebot. GitHub provides [two types](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#types-of-personal-access-tokens) of access tokens: -![GitHub PAT Scope](/images/github_pat_scopes.png) -Next, provide the PAT via the `token` property, either as an environment variable or a secret: + + + Create a new fine-grained PAT [here](https://github.com/settings/personal-access-tokens/new). First, select the resource owner and the repositories that you want Sourcebot to have access to. + + Next, under "Repository permissions", select permissions `Contents` and `Metadata` with access `Read-only`. The permissions should look like the following: + + ![GitHub PAT Scope](/images/github_pat_scopes_fine_grained.png) + + [GitHub docs](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#fine-grained-personal-access-tokens) + + + Create a new PAT [here](https://github.com/settings/tokens/new) and make sure you select the `repo` scope: + + ![GitHub PAT Scope](/images/github_pat_scopes.png) + + [GitHub docs](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#personal-access-tokens-classic) + + + +Next, provide the access token via the `token` property, either as an environment variable or a secret: diff --git a/docs/docs/connections/local-repos.mdx b/docs/docs/connections/local-repos.mdx index 58090886..0791b8f0 100644 --- a/docs/docs/connections/local-repos.mdx +++ b/docs/docs/connections/local-repos.mdx @@ -5,7 +5,7 @@ icon: folder import GenericGitHost from '/snippets/schemas/v3/genericGitHost.schema.mdx' -Sourcebot can sync code from generic git repositories stored in a local directory. This can be helpful in scenarios where you already have a large number of repos already checked out. Local repositories are treated as **read-only**, meaing Sourcebot will **not** `git fetch` new revisions. +Sourcebot can sync code from generic git repositories stored in a local directory. This can be helpful in scenarios where you already have a large number of repos already checked out. Local repositories are treated as **read-only**, meaning Sourcebot will **not** `git fetch` new revisions. ## Getting Started @@ -27,7 +27,7 @@ To get Sourcebot to index these repositories: - We need to mount a docker volume to the `repos` directory so Sourcebot can read it's contents. Sourcebot will **not** write to local repositories, so we can mount a seperate **read-only** volume: + We need to mount a docker volume to the `repos` directory so Sourcebot can read it's contents. Sourcebot will **not** write to local repositories, so we can mount a separate **read-only** volume: ``` bash docker run \ diff --git a/docs/docs/connections/overview.mdx b/docs/docs/connections/overview.mdx index e095b6d6..5165a2aa 100644 --- a/docs/docs/connections/overview.mdx +++ b/docs/docs/connections/overview.mdx @@ -6,12 +6,24 @@ sidebarTitle: Overview import SupportedPlatforms from '/snippets/platform-support.mdx' import ConfigSchema from '/snippets/schemas/v3/index.schema.mdx' -A **connection** in Sourcebot represents a link to a code host (such as GitHub, GitLab, Bitbucket, etc.). 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. +To index your code with Sourcebot, you must provide a configuration file. When running Sourcebot, this file must be mounted in a volume that is accessible to the container, with its +path specified in the `CONFIG_PATH` environment variable. For example: -A JSON configuration file is used to specify connections. For example: +```bash icon="terminal" Passing in a CONFIG_PATH to Sourcebot +docker run \ + -v $(pwd)/config.json:/data/config.json \ + -e CONFIG_PATH=/data/config.json \ + ... \ # other config + ghcr.io/sourcebot-dev/sourcebot:latest +``` -```json -// Specifies two connections: +## Config Schema + +The configuration file defines a set of **connections**. A connection in Sourcebot represents a link to a code host (such as GitHub, GitLab, Bitbucket, etc.). + +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 { "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json", "connections": { @@ -43,16 +55,7 @@ A JSON configuration file is used to specify connections. For example: Configuration files must conform to the [JSON schema](#schema-reference). -When running Sourcebot, this file must be mounted in a volume that is accessible to the container, with its path specified in the `CONFIG_PATH` environment variable. For example: - -```bash -docker run \ - -v $(pwd)/config.json:/data/config.json \ - -e CONFIG_PATH=/data/config.json \ - ... \ # other config - ghcr.io/sourcebot-dev/sourcebot:latest -``` - +## Config Syncing Sourcebot performs syncing in the background. Syncing consists of two steps: 1. Fetch the latest changes from `HEAD` (and any [additional branches](/docs/features/search/multi-branch-indexing)) from the code host. 2. Re-indexes the repository. @@ -70,10 +73,9 @@ On the home page, you can view the sync status of ongoing jobs: src="https://framerusercontent.com/assets/7YyxK8ctPEy9Rf68X2kIdMI.mp4" > -## Getting started ---- +## Platform Connection Guides -To get started, pick a platform below and follow the instructions to connect your code. +To learn more about how to create a connection for a specific code host, check out the guides below. diff --git a/docs/docs/deployment-guide.mdx b/docs/docs/deployment-guide.mdx index 0c515c06..75b09dc4 100644 --- a/docs/docs/deployment-guide.mdx +++ b/docs/docs/deployment-guide.mdx @@ -10,10 +10,10 @@ The following guide will walk you through the steps to deploy Sourcebot on your ## Walkthrough video --- -Watch this 1:51 minute video to get a quick overview of how to deploy Sourcebot using Docker. +Watch this quick walkthrough video to learn how to deploy Sourcebot using Docker.