docs

Author: brendan-kellam

docs/docs/configuration/auth/providers.mdx

@@ -52,6 +52,14 @@ Optional environment variables:
 
 [Auth.js GitLab Provider Docs](https://authjs.dev/getting-started/providers/gitlab)
 
+Authentication using GitLab is supported via a [OAuth2.0 app](https://docs.gitlab.com/integration/oauth_provider/#create-an-instance-wide-application) installed on the GitLab instance. Follow the instructions in the [GitLab docs](https://docs.gitlab.com/integration/oauth_provider/) to create an app. The callback URL should be configurd to `<sourcebot_deployment_url>/api/auth/callback/gitlab`, and the following scopes need to be set:
+
+| Scope      | Required | Notes                                                                                              |
+|------------|----------|----------------------------------------------------------------------------------------------------|
+| read_user  | Yes      | Allows Sourcebot to read basic user information required for authentication.                       |
+| read_api   | Conditional | Required **only** when [permission syncing](/docs/features/permission-syncing) is enabled. Enables Sourcebot to list all repositories and projects for the authenticated user. |
+
+
 **Required environment variables:**
 - `AUTH_EE_GITLAB_CLIENT_ID`
 - `AUTH_EE_GITLAB_CLIENT_SECRET`

docs/docs/features/permission-syncing.mdx

@@ -35,7 +35,7 @@ We are actively working on supporting more code hosts. If you'd like to see a sp
 | Platform | Permission syncing |
 |:----------|------------------------------|
 | [GitHub (GHEC & GHEC Server)](/docs/features/permission-syncing#github) | ✅ |
-| GitLab | 🛑 |
+| [GitLab (Self-managed & Cloud)](/docs/features/permission-syncing#gitlab) | ✅ |
 | Bitbucket Cloud | 🛑 |
 | Bitbucket Data Center | 🛑 |
 | Gitea | 🛑 |
@@ -59,6 +59,18 @@ Permission syncing works with **github.com**, **GitHub Enterprise Cloud**, and *
 - A GitHub OAuth 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](/docs/features/permission-syncing#how-it-works).
 - OAuth tokens must assume the `repo` scope in order to use the [List repositories for the authenticated user API](https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#list-repositories-for-the-authenticated-user) during [User driven syncing](/docs/features/permission-syncing#how-it-works). Sourcebot **will only** use this token for **reads**.
 
+## GitLab
+
+Prerequisite: [Add GitLab as an OAuth provider](/docs/configuration/auth/providers#gitlab).
+
+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](https://docs.gitlab.com/user/project/members/#membership-types).
+
+
+**Notes:**
+- A GitLab OAuth 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](/docs/features/permission-syncing#how-it-works).
+- OAuth tokens require the `read_api` scope in order to use the [List projects for the authenticated user API](https://docs.gitlab.com/ee/api/projects.html#list-all-projects) during [User driven syncing](/docs/features/permission-syncing#how-it-works).
+
+
 # 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: