Skip to content

Cleanup and improve code search docs a bit #1760

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
eseliger wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Cleanup and improve code search docs a bit #1760

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
47a6e4b
Cleanup and improve code search docs a bit
eseliger Apr 26, 2026
c738589
fixup
eseliger Apr 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 19 additions & 19 deletions docs/admin/code-hosts/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,13 @@ Sourcegraph can sync repositories from code hosts and other similar services. We

Tier 1 code hosts are our highest level of support for code hosts. When leveraging a Tier 1 code host, you can expect:

- Scalable repository syncing - Sourcegraph is able to reliably sync repositories from this code host up to 100k repositories. (SLA TBD)
- Scalable permissions syncing - Sourcegraph is able to reliably sync permissions from this code host for up to 10k users. (SLA TBD)
- Authentication - Sourcegraph is able to leverage authentication from this code host (i.e. Login with GitHub).
- Code Search - A developer can seamlessly search across repositories from this code host. (SLAs TBD)
- Code Monitors - A developer can create a code monitor to monitor code in this repository.
- Code Insights - Code Insights reliably works on code sync'd from a tier 1 code host.
- Batch Changes - A Batch Change can be leveraged to submit code changes back to a tier 1 code host while respecting code host permissions.
- Scalable repository syncing - Sourcegraph is able to reliably sync repositories from this code host up to 500k repositories.
- Scalable permissions syncing - Sourcegraph is able to reliably sync permissions from this code host for up to 10k users.
- Authentication - Sourcegraph is able to leverage authentication from this code host (i.e. Login with GitHub).
- Code Search - A developer can seamlessly search across repositories from this code host.
- Code Monitors - A developer can create a code monitor to monitor code in this repository.
- Code Insights - Code Insights reliably works on code sync'd from a tier 1 code host.
- Batch Changes - A Batch Change can be leveraged to submit code changes back to a tier 1 code host while respecting code host permissions.

| Code Host | Status | Repository Syncing | Permissions Syncing | Authentication | Code Search | Code Monitors | Code Insights | Batch Changes |
| ----------------------------- | ------ | ------------------ | ------------------- | -------------- | ----------- | ------------- | ------------- | ------------- |
Expand All @@ -39,23 +39,23 @@ Tier 1 code hosts are our highest level of support for code hosts. When leveragi

We recognize there are other code hosts including CVS, SVN, and many more. Today, we do not offer native integrations with these code hosts and customers are advised to leverage [Src-srv-git](/admin/code-hosts/non-git) and the [explicit permissions API](/admin/permissions/api) as a way to ingest code and permissions respectively into Sourcegraph.

[Src-srv-git](/admin/code-hosts/non-git) and the [explicit permissions API](/admin/permissions/api) follow the same scale guidance shared above (up to 100k repos and 10k users).
[Src-srv-git](/admin/code-hosts/non-git) and the [explicit permissions API](/admin/permissions/api) follow the same scale guidance shared above (up to 500k repos and 10k users).

## Configure a code host connection

**Site admins** can configure Sourcegraph to sync code from the following code hosts:

- [GitHub](/admin/code-hosts/github)
- [GitLab](/admin/code-hosts/gitlab)
- [Bitbucket Cloud](/admin/code-hosts/bitbucket-cloud)
- [Bitbucket Server / Bitbucket Data Center](/admin/code-hosts/bitbucket-server)
- [Azure DevOps](/admin/code-hosts/azuredevops)
- [Gerrit](/admin/code-hosts/gerrit)
- [AWS CodeCommit](/admin/code-hosts/aws-codecommit)
- [Other Git code hosts (using a Git URL)](/admin/code-hosts/other)
- [Non-Git code hosts](/admin/code-hosts/non-git)
- [Perforce](/admin/repo/perforce)
- [Plastic SCM](/admin/repo/plasticscm)
- [GitHub](/admin/code-hosts/github)
- [GitLab](/admin/code-hosts/gitlab)
- [Bitbucket Cloud](/admin/code-hosts/bitbucket-cloud)
- [Bitbucket Server / Bitbucket Data Center](/admin/code-hosts/bitbucket-server)
- [Azure DevOps](/admin/code-hosts/azuredevops)
- [Gerrit](/admin/code-hosts/gerrit)
- [AWS CodeCommit](/admin/code-hosts/aws-codecommit)
- [Other Git code hosts (using a Git URL)](/admin/code-hosts/other)
- [Non-Git code hosts](/admin/code-hosts/non-git)
- [Perforce](/admin/repo/perforce)
- [Plastic SCM](/admin/repo/plasticscm)

## Rate limits

Expand Down
10 changes: 2 additions & 8 deletions docs/admin/permissions/api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,6 @@ E.g. if a code host does not support permission syncing/webhooks or if it would
It's also a good idea to use explicit permissions API if the source of truth for the codehost permissions is already defined in some external system, e.g. LDAP group membership.
In that case, it might be less resource intensive to sync the permissions from external source of truth directly via a periodically running routine.

## SLA

Sourcegraph SLA is, that **p95 of write requests to the explicit permissions API will be resolved within 10 seconds**.

Sourcegraph does not provide SLA for how fresh the permissions are, since the data is provided as is to the API.

## Disadvantages

It is important to note, that when using explicit permissions API, the permissions are written to the database as provided, without further verification that such permissions do exist on the code host side.
Expand All @@ -39,8 +33,8 @@ To enable the permissions API, add the following to the [site configuration](/ad

The `bindID` value specifies how to uniquely identify users when setting permissions:

- `username`: You can [set permissions](#setting-repository-permissions-for-users) for users by specifying their Sourcegraph usernames. Using usernames is **preferred**, as usernames are required to be unique for each user.
- `email`: You can [set permissions](#setting-repository-permissions-for-users) for users by specifying their email addresses (which must be verified primary emails associated with their Sourcegraph user account). This method can lead to unexpected results if there are multiple Sourcegraph user accounts with the same verified email address. Also, the email address is case-sensitive, so it should be exactly the same as set on the sourcegraph UI.
- `username`: You can [set permissions](#setting-repository-permissions-for-users) for users by specifying their Sourcegraph usernames. Using usernames is **preferred**, as usernames are required to be unique for each user.
- `email`: You can [set permissions](#setting-repository-permissions-for-users) for users by specifying their email addresses (which must be verified primary emails associated with their Sourcegraph user account). This method can lead to unexpected results if there are multiple Sourcegraph user accounts with the same verified email address. Also, the email address is case-sensitive, so it should be exactly the same as set on the sourcegraph UI.

After you enable the permissions API, you must [set permissions](#setting-repository-permissions-for-users) to allow users to view repositories (site admins bypass all permissions checks and can always view all repositories).

Expand Down
34 changes: 15 additions & 19 deletions docs/admin/permissions/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,6 @@ To set up permissions by [syncing them from a code host](/admin/permissions/sync
- [Bitbucket Cloud](/admin/auth/#bitbucket-cloud)
- [Bitbucket Server](/admin/auth/#bitbucket-server)
- [Gerrit](/admin/auth/#gerrit)
- Bitbucket Server doesn't require an authentication provider, but has [other prerequisites](/admin/code-hosts/bitbucket-server#prerequisites)
- Perforce doesn't need a separate authentication provider
- [Azure DevOps](/admin/code-hosts/azuredevops)
2. Configure the code host connection to use authorization:
Expand Down Expand Up @@ -68,23 +67,23 @@ To know more about each method that we support, please follow the link above.

Support for repository permissions accross different code hosts is different. The following table captures current state of support (ordered alphabetically):

| Code host | [Permission Syncing](/admin/permissions/syncing) | [Webhooks for Permissions](/admin/permissions/webhooks) | [Explicit API](/admin/permissions/api) | [Scale supported](#supported-scale) |
| ---------------------- | ------------------------------------------------ | ------------------------------------------------------- | -------------------------------------- | ----------------------------------- |
| Bitbucket Cloud (Beta) | ✓ | ✗ | ✓ | 10k users, 100k repositories |
| Bitbucket Server | ✓ | ✗ | ✓ | 10k users, 100k repositories |
| Gerrit (Beta) | ✓ | ✗ | ✓ | 10k users, 100k repositories |
| GitHub | ✓ | ✓ | ✓ | 40k users, 200k repositories |
| GitHub Enterprise | ✓ | ✓ | ✓ | 40k users, 200k repositories |
| GitLab | ✓ | ✗ | ✓ | 40k users, 200k repositories |
| GitLab Self-Managed | ✓ | ✗ | ✓ | 40k users, 200k repositories |
| Perforce (Beta) | Yes (with file-level permissions) | ✓ | ✓ | 10k users, 250k repositories |
| Azure Devops | ✓ | ✓ | ✓ | 10k users, 100k repositories |
| Code host | [Permission Syncing](/admin/permissions/syncing) | [Webhooks for Permissions](/admin/permissions/webhooks) | [Explicit API](/admin/permissions/api) | [Scale supported](#supported-scale) |
| ------------------- | ------------------------------------------------ | ------------------------------------------------------- | -------------------------------------- | ----------------------------------- |
| Bitbucket Cloud | ✓ | ✗ | ✓ | 10k users, 100k repositories |
| Bitbucket Server | ✓ | ✗ | ✓ | 10k users, 100k repositories |
| Gerrit (Beta) | ✓ | ✗ | ✓ | 10k users, 100k repositories |
| GitHub | ✓ | ✓ | ✓ | 40k users, 200k repositories |
| GitHub Enterprise | ✓ | ✓ | ✓ | 40k users, 200k repositories |
| GitLab | ✓ | ✗ | ✓ | 40k users, 200k repositories |
| GitLab Self-Managed | ✓ | ✗ | ✓ | 40k users, 200k repositories |
| Perforce (Beta) | Yes (with file-level permissions) | ✓ | ✓ | 10k users, 250k repositories |
| Azure Devops | ✓ | ✓ | ✓ | 10k users, 100k repositories |

All the other code hosts only support [Explicit permissions API](/admin/permissions/api).
All the other code hosts support the [explicit permissions API](/admin/permissions/api) for deep integrations with external permission management.

### Supported scale

If not otherwise stated in the table above, all code hosts should support up to 10k users and 100k repositories for permission syncing.
If not otherwise stated in the table above, all code hosts support up to 10k users and 100k repositories for permission syncing.

These numbers come from testing the supported scale in a testing environment or running on a customer instance.

Expand All @@ -99,14 +98,11 @@ in Sourcegraph.

- [Permission syncing SLA](/admin/permissions/syncing#sla)
- [Webhooks SLA](/admin/permissions/webhooks#sla)
- [Explicit Permissions API SLA](/admin/permissions/api#sla)

## License requirements

To have permission syncing available, the Sourcegraph instance needs to be configured with
a license that has `acls` feature enabled. If it is not present, Sourcegraph will not enforce
repository permissions and each repository will be treated as public - any user that has access
to Sourcegraph will be able to access it.
To have permission syncing available, you need a valid Sourcegraph license key. Without a license, Sourcegraph will not enforce
repository permissions and each repository will be treated as public - any user that has access to Sourcegraph will be able to access it.

## Site administrators

Expand Down
21 changes: 12 additions & 9 deletions docs/code-navigation/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,9 @@ seoPriority: 1.0

Code Navigation helps you quickly understand your code, its dependencies, and symbols within the Sourcegraph file view while making it easier to move through your codebase via:

- Onboarding to codebases faster with cross-repository code navigation features like [Go to definition](/code-navigation/features#go-to-definition) and [Find references](/code-navigation/features#find-references)
- Providing complete precise reviews, getting up to speed on unfamiliar code, and determining the impact of code changes with the confidence of compiler-accurate code navigation
- Determining the root causes quickly with precise code navigation that tracks references across repositories and package dependencies
- Onboarding to codebases faster with cross-repository code navigation features like [Go to definition](/code-navigation/features#go-to-definition) and [Find references](/code-navigation/features#find-references)
- Providing complete precise reviews, getting up to speed on unfamiliar code, and determining the impact of code changes with the confidence of compiler-accurate code navigation
- Determining the root causes quickly with precise code navigation that tracks references across repositories and package dependencies

<video
width="1920"
Expand Down Expand Up @@ -66,13 +66,13 @@ Code Navigation helps you quickly understand your code, its dependencies, and sy

Code Navigation helps you with the following tasks:

| **Feature** | **Description** |
| ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Feature** | **Description** |
| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Hover](/code-navigation/features#hover) | Quickly view a symbol's type signature and documentation without switching to another source file |
| [Go to definition](/code-navigation/features#go-to-definition) | Click the button or symbol name, navigates you to the symbol's definition |
| [Find references](/code-navigation/features#find-references) | Selecting it in the hover lists all references, definitions, and implementations at the bottom, including precise and search-based results |
| [Find implementations](/code-navigation/features#find-implementations) | Click to go to a symbol's interface definition or, at the interface, see all implementations across repositories, including interfaces implemented by a struct |
| [Perform an action](/code-navigation/features#perform-an-action) | When browsing code, you can perform a couple of actions like open in code host, raw download and view blame. |
| [Perform an action](/code-navigation/features#perform-an-action) | When browsing code, you can perform a couple of actions like open in code host, raw download and view blame. |

<Callout type="note">
Read and learn more about [Code Navigation features here
Expand All @@ -83,10 +83,13 @@ Code Navigation helps you with the following tasks:

There are two types of Code Navigation that Sourcegraph supports:

- [Search-based Code Navigation](/code-navigation/search-based-code-navigation): Works out of the box with most popular programming languages, powered by Sourcegraph's code search. It uses a mix of text search and syntax-level heuristics (no language-level semantic information) for fast, performant searches across large code bases.
- [Precise Code Navigation](/code-navigation/precise-code-navigation): Uses compile-time information to provide users with accurate cross-repository navigation experience across the entire code base.

- [Search-based Code Navigation](/code-navigation/search-based-code-navigation): Works out of the box with most popular programming languages, powered by Sourcegraph's code search. It uses a mix of text search and syntax-level heuristics (no language-level semantic information) for fast, performant searches across large code bases.
- [Precise Code Navigation](/code-navigation/precise-code-navigation): Uses compile-time information to provide users with accurate cross-repository navigation experience across the entire code base.

## Architecture

Learn about how Code Navigation fits into Sourcegraph in the [architecture overview](/admin/architecture#code-navigation).

## What languages are supported?

Search-based code navigation supports 40 programming languages, including all of the most popular ones: Apex, Clojure, Cobol, C++, C#, CSS, Cuda, Dart, Elixir, Erlang, Go, GraphQL, Groovy, Haskell, Java, JavaScript, Jsonnet, Kotlin, Lisp, Lua, OCaml, Pascal, Perl, PHP, PowerShell, Protobuf, Python, R, Ruby, Rust, Scala, Shell, Starlark, Strato, Swift, Tcl, Thrift, TypeScript, Verilog, VHDL.
Loading