Skip to content

permission-syncing.mdx

Latest commit

 

History

History
114 lines (82 loc) · 8.28 KB

permission-syncing.mdx

File metadata and controls

114 lines (82 loc) · 8.28 KB
title Permission syncing
sidebarTitle Permission syncing

import LicenseKeyRequired from '/snippets/license-key-required.mdx'

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 EXPERIMENT_EE_PERMISSION_SYNC_ENABLED environment variable to true.

docker run \
    -e EXPERIMENT_EE_PERMISSION_SYNC_ENABLED=true \
    /* additional args */ \
    ghcr.io/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 🛑
Gitea 🛑
Gerrit 🛑
Generic git host 🛑

Getting started

GitHub

Prerequisites:

  • 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:

GitLab

Prerequisites:

  • 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:

Bitbucket Cloud

Prerequisites:

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](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-repositories/#api-repositories-workspace-repo-slug-permissions-config-users-get) 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:

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 experiment_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 experiment_userDrivenPermissionSyncIntervalMs interval to limit the window of delay.

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.

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. These intervals can be configured using the following settings in the config file:

Setting Type Default Minimum
experiment_repoDrivenPermissionSyncIntervalMs number 24 hours 1
experiment_userDrivenPermissionSyncIntervalMs number 24 hours 1