sourcegraph · eseliger · Feb 26, 2025
diff --git a/.editorconfig b/.editorconfig
@@ -0,0 +1,23 @@
+root = true
+
+[*]
+insert_final_newline = true
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[{*.js,*.jsx,*.json,*.yml,*.yaml,*.md,.babelrc,.stylelintrc,*.proto}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[{*.sh, *.bash}]
+indent_style = space
+indent_size = 2
+switch_case_indent = true
+
+[**/node_modules/**]
+ignore = true
diff --git a/docs/admin/auth/index.mdx b/docs/admin/auth/index.mdx
@@ -102,7 +102,6 @@ Leave the `url` field empty for GitHub.com.
 
 Once you've configured GitHub as a sign-on provider, you may also want to [add GitHub repositories to Sourcegraph](/admin/code_hosts/github#repository-syncing).
 
-
 ### How to control user sign-up and sign-in with GitHub auth provider
 
 You can use the following filters to control how users will create accounts and sign in to your Sourcegraph instance via the GitHub auth provider.
@@ -116,7 +115,6 @@ The new user email, during their account creation, should match one of their Git
 
 > WARNING: If `allowSignup` is set to `true`, anyone with internet access to both your Sourcegraph instance and your GitHub url are able to sign up and login to your instance. In particular, if url is set to `https://github.com`, this means that anyone with a Github account could log in to your Sourcegraph instance and search your indexed code. Make sure to also configure the `allowOrgs` field described below to limit sign-ups to your org, or limit public access to your Sourcegraph instance via IP restrictions / VPN. For assistance, contact support.
 
-
 ```json
   {
     "type": "github",
@@ -533,3 +531,11 @@ Usernames from authentication providers are normalized before being used in Sour
 For example, a user whose external username (according the authentication provider) is `[email protected]` would have the Sourcegraph username `alice-smith`.
 
 If multiple accounts normalize into the same username, separate accounts are still created, but Sourcegraph will add a randomized suffix to the username to ensure uniqueness.
+<<<<<<< Updated upstream
+=======
+
+## Remind users to connect external accounts
+
+When repository permissions are enabled, users must link their external code host accounts with their Sourcegraph accounts to access private repositories.
+To ensure users are aware of any unlinked accounts, users will be prompted to connect any missing external accounts upon visiting Sourcegraph for the first time, or when the provider configuration changes.
+>>>>>>> Stashed changes
diff --git a/docs/admin/auth/saml/azure_ad.mdx b/docs/admin/auth/saml/azure_ad.mdx
@@ -4,15 +4,16 @@
 
 1. In Microsoft Entra ID, create an unlisted (non-gallery) application [following the official documentation](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/add-non-gallery-app).
 1. Once the application is created, follow [these instructions to enable SAML SSO](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/configure-single-sign-on-non-gallery-applications). Use these configuration values (replacing "sourcegraph.example.com" with your Sourcegraph instance URL):
-  * **Identifier (Entity ID):** `https://sourcegraph.example.com/.auth/saml/metadata`
-  * **Reply URL (Assertion Consumer Service URL):** `https://sourcegraph.example.com/.auth/saml/acs`
-  * **Sign-on URL, Relay State, and Logout URL** can be left empty.
-  * **User Attributes & Claims:** Add the following attributes.
-    - `emailaddress`: user.mail (required)
-    - `name`: user.userprincipalname (optional)
-    - `login`: user.userprincipalname (optional)
-  * **Name ID**: `email`
-  * You can leave the other configuration values set to their defaults.
+  - **Identifier (Entity ID):** `https://sourcegraph.example.com/.auth/saml/metadata`
+  - **Reply URL (Assertion Consumer Service URL):** `https://sourcegraph.example.com/.auth/saml/acs`
+  - **Sign-on URL** `https://sourcegraph.example.com/.auth/saml/login?pc=azure`
+  - **Relay State, and Logout URL** can be left empty.
+  - **User Attributes & Claims:** Add the following attributes.
+    - `emailaddress`: user.mail
+    - `name`: user.userprincipalname
+    - `login`: user.userprincipalname
+    - `Unique user identifier`: `user.objectid`
+  - You can leave the other configuration values set to their defaults.
 1. Record the value of the "App Federation Metadata Url". You'll need this in the next section.
 
 ## 2. Add the SAML auth provider to Sourcegraph site config
@@ -27,10 +28,11 @@
    {
      "type": "saml",
      "configID": "azure",
-     "identityProviderMetadataURL": "https://login.microsoftonline.com/7d2a00ed-73e8-4920-bbfa-ef68effe2d1e/federationmetadata/2007-06/federationmetadata.xml?appid=eff20ae4-145b-4bd3-ff3f-21edab43fe99"
+     "identityProviderMetadataURL": "https://login.microsoftonline.com/7d2a00ed-73e8-4920-bbfa-ef68effe2d1e/federationmetadata/2007-06/federationmetadata.xml?appid=eff20ae4-145b-4bd3-ff3f-21edab43fe99",
+     "allowSignup": true
    }
  ]
 }
 ```
 
-> NOTE: Optional, but recommended: [add automatic provisioning of users with SCIM](/admin/scim).
+<Callout type="note">Optional, but recommended: [add automatic provisioning of users with SCIM](/admin/scim).</Callout>
diff --git a/docs/admin/auth/saml/okta.mdx b/docs/admin/auth/saml/okta.mdx
@@ -11,12 +11,13 @@
       - For “Single sign on URL”, set the value to `<URL>`/.auth/saml/acs
         - Under this box, there should be a checkbox labeled “Use this for Recipient URL and Destination URL”. Check the box if it is not already selected.
       - For “Audience URI (SP Entity ID)”, set the value to `<URL>`/.auth/saml/metadata
-      - For "Name ID format", choose "EmailAddress"
+      - For "Name ID format", choose "Persistent"
+      - For "Application username", choose "Custom" and insert `user.getInternalProperty("id")`.
     - In the section titled “Attribute Statements (optional)”:
       - Set the following Name and Values, leaving the Name format to “Unspecified”
-      - Email: user.email (This one is required)
-      - Login: user.login (This one is optional)
-      - displayName: user.firstName (This one is optional)
+      - `email`: `user.email`
+      - `login`: `user.login`
+      - `displayName`: `user.firstName` or an alternative field
 6. Click Next.
 7. Now you should be on the “Feedback” step. Select the radio button for “I’m an Okta customer adding an internal app”, and provide feedback if you wish. Click "Finish".
 8. You should now be on the Application page for Sourcegraph, where you can view the settings and configurations you have just set. You will want to grant users or groups sign-in access before moving on.
@@ -52,4 +53,4 @@
 }
 ```
 
-> NOTE: Optional, but recommended: [add automatic provisioning of users with SCIM](/admin/scim).
+<Callout type="note">Optional, but recommended: [add automatic provisioning of users with SCIM](/admin/scim).</Callout>
diff --git a/docs/admin/code_hosts/gitlab.mdx b/docs/admin/code_hosts/gitlab.mdx
@@ -98,38 +98,6 @@ Then, [add or edit a GitLab connection](#repository-syncing) and include the `au
 In this case, a user's OAuth token will be used to get a list of repositories that the user can access.
 [Repository-centric permissions syncing](/admin/permissions/syncing) will be disabled.
 
-### Administrator (sudo-level) access token
-
-This method requires administrator access to GitLab so that Sourcegraph can access the [admin GitLab Users API endpoint](https://docs.gitlab.com/ee/api/users.html#for-admins). For each GitLab user, this endpoint provides the user ID that comes from the authentication provider, so Sourcegraph can associate a user in its system to a user in GitLab.
-
-Prerequisite: Add the [SAML](/admin/auth/#saml) or [OpenID Connect](/admin/auth/#openid-connect)
-authentication provider you use to sign into GitLab.
-
-Then, [add or edit a GitLab connection](#repository-syncing) using an administrator (sudo-level) personal access token, and include the `authorization` field:
-
-```json
-{
-  "url": "https://gitlab.com",
-  "token": "$PERSONAL_ACCESS_TOKEN",
-  // ...
-  "authorization": {
-    "identityProvider": {
-      "type": "external",
-      "authProviderID": "$AUTH_PROVIDER_ID",
-      "authProviderType": "$AUTH_PROVIDER_TYPE",
-      "gitlabProvider": "$AUTH_PROVIDER_GITLAB_ID"
-    }
-  }
-}
-```
-
-`$AUTH_PROVIDER_ID` and `$AUTH_PROVIDER_TYPE` identify the authentication provider to use and should
-match the fields specified in the authentication provider config
-(`auth.providers`). The authProviderID can be found in the `configID` field of the auth provider config.
-
-`$AUTH_PROVIDER_GITLAB_ID` should match the `identities.provider` returned by
-[the admin GitLab Users API endpoint](https://docs.gitlab.com/ee/api/users.html#for-admins).
-
 ### Username
 
 Prerequisite: Ensure that `http-header` is the *only* authentication provider type configured for
@@ -296,7 +264,7 @@ See [Internal rate limits](/admin/code_hosts/rate_limits#internal-rate-limits).
 	// It is important that the Sourcegraph repository name generated with this pattern be unique to this code host. If different code hosts generate repository names that collide, Sourcegraph's behavior is undefined.
 	"repositoryPathPattern": "{host}/{pathWithNamespace}",
 
-	// A GitLab access token with "api" scope. Can be a personal access token (PAT) or an OAuth token. If you are enabling permissions with identity provider type "external", this token should also have "sudo" scope.
+	// A GitLab access token with "api" scope. Can be a personal access token (PAT) or an OAuth token. If you are enabling permissions with identity provider type "username", this token should also have "sudo" scope.
 	"token": null,
 
 	// The OAuth token expiry (Unix timestamp in seconds)

diff --git a/docs/admin/config/authorization_and_authentication.mdx b/docs/admin/config/authorization_and_authentication.mdx
@@ -68,48 +68,13 @@ Once authentication with GitHub via OAuth is configured, follow [these steps to
 
 ### GitLab Enterprise or GitLab Cloud authentication and authorization
 
-We support both authentication and permissions syncing (through OAuth) for GitLab. If you use GitLab as your code host, you have two available authentication flows:
-
-#### Option 1
+We support both authentication and permissions syncing (through OAuth) for GitLab.
 
 1. Use SAML (or another auth mechanism) to log in to GitLab
 2. Use GitLab OAuth to log in to Sourcegraph
 
 In this way, access to Sourcegraph will still be managed by your identity provider, using the code host as a middle step. This option is the simplest to configure. To do so, [set up GitLab as an authentication option](/admin/auth/#gitlab), and then [enable permissions syncing](/admin/code_hosts/gitlab#oauth-application).
 
-#### Option 2
-
-Alternatively, you can configure SAML authentication in Sourcegraph, and use GitLab permissions syncing in the background to control access permissions. To implement this method, you will need to make sure that GitLab is able to return a value in `identities.provider` for the `GET /users` endpoint ([GitLab documentation](https://docs.gitlab.com/ee/api/users.html#for-admins)) that your identity provider is able to pass as the `nameID` in the SAML response. If that isn’t possible, you will need to use the first option.
-
-To configure SAML auth with GitLab permissions, you will need to first [configure permissions from GitLab](/admin/code_hosts/gitlab#administrator-sudo-level-access-token). Then, [configure SAML authentication](/admin/auth/saml/). The `nameID` passed by the identity provider will need to match the value of `identities.provider`.
-
-For example, if the GitLab API returns:
-
-```json
-{
-  "identities": [{ "provider": "saml", "extern_uid": "[email protected]" }]
-}
-```
-
-Then you will need to configure permission in Sourcegraph as:
-
-```json
-{
-  "url": "https://gitlab.com",
-  "token": "$PERSONAL_ACCESS_TOKEN",
-  "authorization": {
-    "identityProvider": {
-      "type": "external",
-      "authProviderID": "$AUTH_PROVIDER_ID",
-      "authProviderType": "$AUTH_PROVIDER_TYPE",
-      "gitlabProvider": "saml"
-    }
-  }
-}
-```
-
-And configure the identity provider to pass the email address as the `nameID`.
-
 ### Bitbucket Server / Bitbucket Data Center authorization
 
 We do not currently support OAuth for Bitbucket Server or Bitbucket Data Center. You will need to combine permissions syncing from Bitbucket Server / Bitbucket Data Center with another authentication mechanism (SAML, built-in auth, HTTP authentication proxies). Bitbucket Server and Bitbucket Data Center only pass usernames to Sourcegraph, so you’ll need to make sure that those usernames are matched by whatever mechanism you choose to use for access.

diff --git a/docs/admin/config/email.mdx b/docs/admin/config/email.mdx
@@ -7,7 +7,7 @@ Sourcegraph uses an SMTP server of your choosing to send emails for:
 - Important updates to a user accounts (for example, creation of API keys)
 - For [`builtin` authentication](/admin/auth/#builtin-password-authentication), password resets and email verification
 
-> NOTE: Sourcegraph Cloud customers can take advantage of mananged SMTP servers - [learn more](/cloud/#managed-smtp).
+<Callout type="note">Sourcegraph Cloud customers can take advantage of mananged SMTP servers - [learn more](/cloud/#managed-smtp).</Callout>
 
 ## User email verification
 
@@ -82,8 +82,8 @@ Make sure that `[email protected]` in both places of the configuration matches th
 
 Other providers such as Mailchimp and Sendgrid may also be used with Sourcegraph. Any valid SMTP server account should do. For those two providers in specific, you may follow their documentation:
 
-* https://mailchimp.com/developer/transactional/docs/smtp-integration/
-* https://docs.sendgrid.com/for-developers/sending-email/getting-started-smtp
+- [https://mailchimp.com/developer/transactional/docs/smtp-integration/](https://mailchimp.com/developer/transactional/docs/smtp-integration/)
+- [https://docs.sendgrid.com/for-developers/sending-email/getting-started-smtp](https://docs.sendgrid.com/for-developers/sending-email/getting-started-smtp)
 
 Once you have an SMTP account, simply navigate to your site configuration (e.g. `https://sourcegraph.com/site-admin/configuration`) and fill in the configuration:
 

diff --git a/docs/admin/config/webhooks/outgoing.mdx b/docs/admin/config/webhooks/outgoing.mdx
@@ -1,6 +1,10 @@
 # Outgoing webhooks
 
+<<<<<<< Updated upstream
 <Callout type="note"> This feature is supported on Sourcegraph versions 5.0 or more.</Callout>
+=======
+<Callout type="note"> This feature is currently in beta and supported on Sourcegraph versions 5.0 or later.</Callout>
+>>>>>>> Stashed changes
 
 Outgoing webhooks can be configured on a Sourcegraph instance in order to send Sourcegraph events to external tools and services. This allows for deeper integrations between Sourcegraph and other applications.
 

diff --git a/docs/admin/permissions/index.mdx b/docs/admin/permissions/index.mdx
@@ -124,6 +124,7 @@ of `alice` are the following union set: [`horsegraph/global`, `horsegraph/hay-v1
 ### Configuration
 
 **Prerequisites:**
+
 1. Sourcegraph version 5.0+
 1. Go to **Site Admin > Migrations** page. There is a migration called `Migrate data from user_permissions table to unified user_repo_permissions.`.
 Make sure that it finished migrating all the data (it reports as 100%). Contact support if the migration does not seem to complete for a long time (multiple days).
@@ -150,8 +151,8 @@ permission sync, it will replace the existing set of synced permissions for that
 
 **Example**:
 
-Let's follow the example from above, `alice` has existing synced permissions to repositories `horsegraph/global` and `horsegraph/hay-v1`
-and explicit permissions to `horsegraph/hay-dev`, meaning a unioned set of effective permissions of [`horsegraph/global`, `horsegraph-hay-v1`, `horsegraph/hay-dev`].
+Let's follow the example from above. `alice` has existing synced permissions for the repositories `horsegraph/global` and `horsegraph/hay-v1`
+and explicit permissions set for `horsegraph/hay-dev`, meaning a unioned set of effective permissions of [`horsegraph/global`, `horsegraph/hay-v1`, `horsegraph/hay-dev`].
 
 An update comes in from permission sync, now returning `alice` permissions as [`horsegraph/global`, `horsegraph/hay-v2`]. Notice
 the removal of `horsegraph-v1` from the set.

diff --git a/docs/admin/permissions/syncing.mdx b/docs/admin/permissions/syncing.mdx
@@ -10,6 +10,7 @@ permissions. Both are on by default, resulting in double polling:
 Sourcegraph collects this information and stores it in internal database.
 
 To see which code hosts support permission syncing, please refer to [Supported code hosts table](/admin/#supported-code-hosts).
+
 ## How it works
 
 ### Periodic sync
@@ -27,6 +28,7 @@ Besides periodic schedule of jobs, we also have a way to request permission sync
 or repository on-demand. This is useful for example when a new user is added to Sourcegraph.
 
 To do that, the following GraphQL request needs to be made:
+
 ```graphql
 mutation {
     scheduleUserPermissionsSync(user: "user") {
@@ -36,6 +38,7 @@ mutation {
 ```
 
 Or in the case of adding a repository, the following request is made:
+
 ```graphql
 mutation {
     scheduleRepositoryPermissionsSync(repository: "repository") {
@@ -45,6 +48,7 @@ mutation {
 ```
 
 **Example**:
+
 - User `bob` is added to Sourcegraph.
 - `bob` has access to repositories `horsegraph/global` and `horsegraph/bob` on the code host
 - an on-demand request is made to sync repository permissions of `bob`, this job is added to the queue with high priority, so it will be processed
@@ -69,6 +73,7 @@ processed. To avoid overloading the code host a sync job [might not be processed
 and depending on the code host, might be heavily rate limited.
 
 Priority queue is needed to process the sync jobs in the order of most important first. E.g.:
+
 - on-demand sync is high priority
 - sync of entities with no permissions is high priority
 - sync of oldest permissions is normal priority, since we already do have some permissions in the system
@@ -230,13 +235,14 @@ mentioned above. Even if we let permission sync consume all the rate limit and w
 is rarely the case. Depending on the code host, the rate limit might be much higher, but then we might be
 firing huge amounts of requests to the code host.
 
-> IMPORTANT: For permission syncing to be quicker, the code host needs to be able to handle big amounts of requests per hour.
+<Callout type="warning">IMPORTANT: For permission syncing to be quicker, the code host needs to be able to handle big amounts of requests per hour.</Callout>
 
-> IMPORTANT: Depending on the customer scale, the amount of users, repositories and the distribution of permissions accross them, the time it takes to fully sync will vary.
+<Callout type="warning">IMPORTANT: Depending on the customer scale, the amount of users, repositories and the distribution of permissions accross them, the time it takes to fully sync will vary.</Callout>
 
-> IMPORTANT: We recommend **configuring webhooks for permissions on GitHub** which makes lag time much smaller.
+<Callout type="warning">IMPORTANT: We recommend **configuring webhooks for permissions on GitHub** which makes lag time much smaller.</Callout>
 
 ## Configuration
+
 There are variety of options in the site configuration to tune how the permissions sync requests are
 scheduled. Default values are shown below:
 
@@ -268,7 +274,9 @@ Internal rate limiter settings are described on each code host configuration pag
 ### Recommendations
 
 #### Less users than repositories
+
 If there are a lot less users, than repositories, it is better to rely on user-centric perms sync instead of repo-centric sync. In that case, we recommend:
+
 ```json
 {
   // ...
@@ -288,6 +296,7 @@ a minute. `5000/(4 * 60) = 20.8`, so the scheduler needs to schedule 21 users on
 
 The rate limit for the code host would need to be changed to support the load. In that case the recommendation
 is to set it to 2x of the amount of [requests expected from permission syncing](#request-count).
+
 #### More users than repositories
 
 If the situation is reversed, it is recommended to do the opposite than above. Prefer repo-centric