only available in a paid plan. Please activate a license key to use this feature.

Overview

Permission syncing allows you to sync Access Permission Lists (ACLs) from a code host to Sourcebot. When configured, users signed into Sourcebot will only be able to access repositories that they have access to on the code host. Practically, this means:

Code Search results will only include repositories that the user has access to.
Code navigation results will only include repositories that the user has access to.
MCP results will only include results from repositories the user has access to.
Ask Sourcebot (and the underlying LLM) will only have access to repositories that the user has access to.
File browsing is scoped to the repositories that the user has access to.

Permission syncing can be enabled by setting the PERMISSION_SYNC_ENABLED environment variable to true.

docker run \
    -e PERMISSION_SYNC_ENABLED=true \
    /* additional args */ \
    docker.sourcebot.dev/sourcebot-dev/sourcebot:latest

Enabling permission syncing on an existing deployment may result in errors that look like “User does not have an OAuth access token…”. This is because the OAuth access token associated with the user’s existing account does not have the correct scopes necessary for permission syncing. To fix, have the user re-authenticate to refresh their access token by either logging out of Sourcebot and logging in again or unlinking and re-linking their account.

Platform support

We are actively working on supporting more code hosts. If you’d like to see a specific code host supported, please reach out.

Platform	Permission syncing
GitHub (GHEC & GHEC Server)	✅
GitLab (Self-managed & Cloud)	✅
Bitbucket Cloud	🟠 Partial
Bitbucket Data Center	🟠 Partial
Azure DevOps Cloud	🛑
Azure DevOps Server	🛑
Gitea	🛑
Gerrit	🛑
Generic git host	🛑

Getting started

GitHub

Prerequisites:

Configure a GitHub connection.
Configure GitHub as an external identity provider.
If you are using a self-hosted GitHub instance, you must also set the baseUrl property of the github identity provider in the config file to the base URL of your GitHub instance (e.g. https://github.example.com).

Permission syncing works with GitHub.com, GitHub Enterprise Cloud, and GitHub Enterprise Server. For organization-owned repositories, users that have read-only access (or above) via the following methods will have their access synced to Sourcebot:

Outside collaborators
Organization members that are direct collaborators
Organization members with access through team memberships
Organization members with access through default organization permissions
Organization owners.

Notes:

A GitHub external identity provider must be configured to (1) correlate a Sourcebot user with a GitHub user, and (2) to list repositories that the user has access to for User driven syncing.
OAuth tokens must assume the repo scope in order to use the List repositories for the authenticated user API during User driven syncing. Sourcebot will only use this token for reads.

GitLab

Prerequisites:

Configure a GitLab connection.
Configure GitLab as an external identity provider.
If you are using a self-hosted GitLab instance, you must also set the baseUrl property of the gitlab identity provider in the config file to the base URL of your GitLab instance (e.g. https://gitlab.example.com).

Permission syncing works with GitLab Self-managed and GitLab Cloud. Users with Guest role or above with membership to a group or project will have their access synced to Sourcebot. Both direct and indirect membership to a group or project will be synced with Sourcebot. For more details, see the GitLab docs. Notes:

A GitLab external identity provider must be configured to (1) correlate a Sourcebot user with a GitLab user, and (2) to list repositories that the user has access to for User driven syncing.
OAuth tokens require the read_api scope in order to use the List projects for the authenticated user API during User driven syncing.
Internal GitLab projects are not enforced by permission syncing and therefore are visible to all users. Only private projects are enforced.

Bitbucket Cloud

Prerequisites:

Configure a Bitbucket Cloud connection.
Configure Bitbucket Cloud as an external identity provider.

Permission syncing works with Bitbucket Cloud. OAuth tokens must assume the account and repository scopes.

Partial coverage for repo-driven syncing. Bitbucket Cloud’s repository user permissions API only returns users who have been directly and explicitly granted access to a repository. Users who have access via any of the following are not captured by repo-driven syncing:

Membership in a group that is added to the repository
Membership in the project that contains the repository
Membership in a group that is part of a project containing the repository

These users will still gain access via user-driven syncing, which fetches all private repositories accessible to each authenticated user. However, there may be a delay between when a repository is added and when affected users gain access in Sourcebot (up to the userDrivenPermissionSyncIntervalMs interval, which defaults to 24 hours).If your workspace relies heavily on group or project-level permissions rather than direct user grants, we recommend reducing the userDrivenPermissionSyncIntervalMs interval to limit the window of delay.

When a Bitbucket Cloud account is closed by its owner, Atlassian applies an account-deletion grace period (currently 14 days for consumer accounts) before the account is fully purged. During this window, Bitbucket’s permission APIs may continue to return the closed user in repository permission lists. Sourcebot revokes that user’s access once the next permission sync receives an authentication error from Bitbucket, or once Atlassian fully purges the account.

Notes:

A Bitbucket Cloud external identity provider must be configured to (1) correlate a Sourcebot user with a Bitbucket Cloud user, and (2) to list repositories that the user has access to for User driven syncing.
OAuth tokens require the account and repository scopes. The repository scope is required to list private repositories during User driven syncing.

Bitbucket Data Center

Prerequisites:

Configure a Bitbucket Data Center connection.
Configure Bitbucket Data Center as an external identity provider.

Permission syncing works with Bitbucket Data Center. OAuth tokens must assume the PUBLIC_REPOS and REPO_READ scopes.

Partial coverage for repo-driven syncing. Repo-driven syncing only captures users who have been directly and explicitly granted access to the repository. Users who have access via any of the following are not captured by repo-driven syncing:

Project-level permissions (inherited by all repos in the project)
Group membership

These users will still gain access via user-driven syncing, which fetches all repositories accessible to each authenticated user using the REPO_READ scope. However, there may be a delay between when access is granted and when affected users see the repository in Sourcebot (up to the userDrivenPermissionSyncIntervalMs interval, which defaults to 24 hours).If your instance relies heavily on project or group-level permissions, we recommend reducing the userDrivenPermissionSyncIntervalMs interval to limit the window of delay.

Notes:

A Bitbucket Data Center external identity provider must be configured to (1) correlate a Sourcebot user with a Bitbucket Data Center user, and (2) to list repositories that the user has access to for User driven syncing.
The connection token must have Repository Read permissions so Sourcebot can read repository-level user permissions for Repo driven syncing.
OAuth tokens require the REPO_READ scope to list accessible repositories during User driven syncing.

Manually refreshing permissions

If a user’s permissions have changed and they need access updated immediately (without waiting for the next scheduled sync), they can trigger a manual refresh from the Linked Accounts page:

Navigate to Settings → Linked Accounts.
Click the Connected button next to the relevant code host account.
Select Refresh Permissions from the dropdown.

The button will show a spinner while the sync is in progress and display a confirmation once it completes.

Overriding enforcement per connection

Each connection supports two flags that control permission enforcement for that connection’s repositories:

enforcePermissions: Controls whether repository permissions are enforced for the connection. When PERMISSION_SYNC_ENABLED is false, this setting has no effect. Defaults to the value of PERMISSION_SYNC_ENABLED.
enforcePermissionsForPublicRepos: Controls whether repository permissions are enforced for public repositories in the connection. When true, public repositories are only visible to users with a linked account for the connection’s code host. When false, public repositories are visible to all users. Has no effect when enforcePermissions is false. Defaults to false.

These flags are useful when you want different enforcement behavior across connections. For example, you may want to enforce permissions on an internal GitHub Enterprise connection while leaving a public-facing Gerrit mirror open to all users. Or, you can use enforcePermissionsForPublicRepos to restrict public repositories on a Bitbucket connection so that only users who have authenticated with that host can browse them.

{
  "connections": {
    "my-github": {
      "type": "github",
      "enforcePermissions": true
    },
    "my-bitbucket": {
      "type": "bitbucket",
      "enforcePermissions": true,
      "enforcePermissionsForPublicRepos": true
    },
    "my-gerrit": {
      "type": "gerrit",
      "url": "https://gerrit.example.com",
      "enforcePermissions": false
    }
  }
}

The table below shows when permissions are enforced based on the combination of PERMISSION_SYNC_ENABLED, enforcePermissions, and enforcePermissionsForPublicRepos:

`PERMISSION_SYNC_ENABLED`	`enforcePermissions`	`enforcePermissionsForPublicRepos`	Private repos enforced?	Public repos enforced?
`true`	`true`	`false`	Yes	No
`true`	`true`	`true`	Yes	Yes
`true`	`false`	any	No	No
`false`	any	any	No	No

How it works

Permission syncing works by periodically syncing ACLs from the code host(s) to Sourcebot to build an internal mapping between Users and Repositories. This mapping is hydrated in two directions:

User driven : fetches the list of all repositories that a given user has access to.
Repo driven : fetches the list of all users that have access to a given repository.

User driven and repo driven syncing occurs every 24 hours by default. Repo-driven syncing can be disabled independently using the following environment variable:

Environment variable	Default	Description
`PERMISSION_SYNC_REPO_DRIVEN_ENABLED`	`true`	Enables/disables repo-driven syncing.

The sync intervals can be configured using the following settings in the config file:

Setting	Type	Default	Minimum
`repoDrivenPermissionSyncIntervalMs`	number	24 hours	1
`userDrivenPermissionSyncIntervalMs`	number	24 hours	1

FAQ

What happens if there are transient errors with the code host?

It depends on the type of error:

Authentication errors (such as 401, 403, 410, or a token refresh failure): Sourcebot immediately revokes the affected user’s access to repositories on that code host.
Rate limits or 5xx responses: Sourcebot keeps the user’s existing access.

When is a visibility change of a repo (switching from public to private) reflected within Sourcebot?

The visibility state of a repository is updated when the connection belonging to that repository is synced, not when the repository’s permissions are synced. Until the next connection sync runs, Sourcebot continues to apply the repository’s previous public/private classification. The connection sync interval is configurable via the resyncConnectionIntervalMs setting in the config file and defaults to 24 hours. Lower this value if you require faster propagation of visibility changes.

Getting Started

Features

Configuration

Subscribe

Misc

Upgrade

Permission syncing

Overview

Platform support

Getting started

GitHub

GitLab

Bitbucket Cloud

Bitbucket Data Center

Manually refreshing permissions

Overriding enforcement per connection

How it works

FAQ

What happens if there are transient errors with the code host?

When is a visibility change of a repo (switching from public to private) reflected within Sourcebot?

​Overview

​Platform support

​Getting started

​GitHub

​GitLab

​Bitbucket Cloud

​Bitbucket Data Center

​Manually refreshing permissions

​Overriding enforcement per connection

​How it works

​FAQ

​What happens if there are transient errors with the code host?

​When is a visibility change of a repo (switching from public to private) reflected within Sourcebot?

Overview

Platform support

Getting started

GitHub

GitLab

Bitbucket Cloud

Bitbucket Data Center

Manually refreshing permissions

Overriding enforcement per connection

How it works

FAQ

What happens if there are transient errors with the code host?

When is a visibility change of a repo (switching from public to private) reflected within Sourcebot?