From f4384da7bd7728c7e07ecf1c50ea0998ef1c5e73 Mon Sep 17 00:00:00 2001 From: Erik Seliger Date: Thu, 14 Aug 2025 19:45:57 +0200 Subject: [PATCH 1/6] oauth: Add documentation on OAuth integrations and M2M credentials Closes SRC-1356. Test plan: Review. --- .../admin/access_control/service_accounts.mdx | 41 +- docs/admin/oauth_apps.mdx | 352 ++++++++++++++++++ docs/api/graphql/index.mdx | 22 +- docs/api/stream_api/index.mdx | 16 +- src/data/navigation.ts | 1 + 5 files changed, 424 insertions(+), 8 deletions(-) create mode 100644 docs/admin/oauth_apps.mdx diff --git a/docs/admin/access_control/service_accounts.mdx b/docs/admin/access_control/service_accounts.mdx index bc7f32fc7..5f81f4e4c 100644 --- a/docs/admin/access_control/service_accounts.mdx +++ b/docs/admin/access_control/service_accounts.mdx @@ -24,13 +24,50 @@ You'll be presented with some next steps you might want to take, like creating a ## Managing Access Tokens -Service accounts authenticate using access tokens rather than passwords. For detailed information about creating, managing, and using access tokens, see: +Service accounts can authenticate using either traditional access tokens or M2M (machine-to-machine) OAuth credentials. + +### Traditional Access Tokens + +For detailed information about creating, managing, and using traditional access tokens, see: - [Creating an access token](/cli/how-tos/creating_an_access_token) - [Managing access tokens](/cli/how-tos/managing_access_tokens) - [Revoking an access token](/cli/how-tos/revoking_an_access_token) -Use service account access tokens to access Sourcegraph's [GraphQL API](/api/graphql). +### M2M OAuth Credentials (Client Credentials Flow) + +M2M credentials provide short-lived tokens via the OAuth client credentials flow expiring after 1 hour. + +**Creating M2M credentials:** + +1. Navigate to the service account's user settings +2. Go to **Access tokens** → **M2M credentials** +3. Click **Create M2M credential** +4. Provide a descriptive **Name** and optional **Description** +5. Select scopes +6. Click **Create** to generate client credentials (client ID and secret) + +**Important:** Store the client secret securely - it won't be displayed again after creation. + +**Using M2M credentials:** + +```bash +# Get an access token using client credentials +curl -X POST https://sourcegraph.example.com/.auth/idp/oauth/token \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "grant_type=client_credentials" \ + -d "client_id=YOUR_CLIENT_ID" \ + -d "client_secret=YOUR_CLIENT_SECRET" \ + -d "scope=user:all" + +# Use the returned access_token for API calls +curl -H "Authorization: Bearer ACCESS_TOKEN" \ + https://sourcegraph.example.com/.api/graphql +``` + +See [OAuth Apps → Client Credentials Flow](/admin/oauth_apps#oauth-flow-examples) for more details on the client credentials flow. + +Both authentication methods can be used to access Sourcegraph's [GraphQL API](/api/graphql) and [Stream API](/api/stream_api). ## Role-Based Access Control (RBAC) diff --git a/docs/admin/oauth_apps.mdx b/docs/admin/oauth_apps.mdx new file mode 100644 index 000000000..13a08a7dc --- /dev/null +++ b/docs/admin/oauth_apps.mdx @@ -0,0 +1,352 @@ +# OAuth Apps + +OAuth Apps let you build rich third-party experiences that call Sourcegraph **on behalf of end-users while honoring their repository permissions**. Every API request made with an OAuth access token is evaluated against the same authorization rules that apply inside the Sourcegraph UI, so your integration only sees the code each user is allowed to see. + +This makes OAuth the preferred choice for any multi-user integration like browser extensions, IDE plugins, chatbots, internal tools, or SaaS platforms where you need to: + +- Authenticate users with familiar Sourcegraph credentials +- Operate without ever handling or storing users' passwords +- Rely on short-lived, scoped tokens that can be revoked at any time +- Guarantee that repository visibility and other access controls are enforced automatically + +OAuth Apps follow standards [RFC 6749](https://tools.ietf.org/html/rfc6749), [RFC 7636 (PKCE)](https://tools.ietf.org/html/rfc7636), and [RFC 8628 (Device Authorization Grant)](https://tools.ietf.org/html/rfc8628). + +Consider using **M2M (client-credentials) service-account tokens** or traditional [access tokens](/admin/access_control/access_tokens) for server-to-server communication, automated scripts, CI/CD pipelines, or single-user applications that do not require per-user permission checks. See [service accounts](/admin/access_control/service_accounts#m2m-oauth-credentials-client-credentials-flow) for details. + +## Creating an OAuth App + +Site admins can create OAuth Apps in the site admin area: + +1. Navigate to **Site admin > OAuth clients** +2. Click **Create OAuth client** +3. Provide the following information: + - **Name**: A descriptive name for your application + - **Description**: (Optional) Additional details about the app's purpose + - **Redirect URI**: The URL where users will be redirected after authorization + - **Client type**: Choose between **Public** or **Private** + - **Scopes**: Select the permissions your app needs + +4. Click **Create** to generate the OAuth client + +After creation, you'll receive: + +- **Client ID**: Public identifier for your application +- **Client Secret**: (Private clients only) Secret key for authentication + +Store the client secret securely. It won't be displayed again after initial creation. + +## Client Types + +### Public Clients + +Public clients are designed for applications that cannot securely store client secrets: + +- **Browser-based applications** (SPAs) +- **Mobile applications** +- **Desktop applications** + +Public clients: + +- Do not receive a client secret +- Must use PKCE (Proof Key for Code Exchange) for security +- Support RFC 8628 Device Authorization Grant flow +- Are suitable for environments where the client code is publicly accessible + +### Private Clients + +Private clients can securely store client secrets: + +- **Server-side web applications** +- **Backend services** +- **Secure server environments** + +Private clients: + +- Receive both client ID and client secret +- Can use the standard authorization code flow (PKCE strongly recommended) +- Allow client authentication with a secret and server-side code exchange + +## Available Scopes + +When creating an OAuth app, select the minimum scopes necessary for your application: + +| Scope | Description | +|-------|-------------| +| `openid` | Required for OpenID Connect authentication | +| `profile` | Access to user profile information (name, picture, etc.) | +| `email` | Access to user's email address | +| `offline_access` | Request refresh tokens for offline access | +| `user:all` | Full access to Sourcegraph API on behalf of the user | + +The `user:all` scope is required for GraphQL API access with OAuth tokens. + +## OAuth endpoints reference + +| Endpoint | URL | +|----------|-----| +| Authorization | `https://sourcegraph.example.com/.auth/idp/oauth/authorize` | +| Token | `https://sourcegraph.example.com/.auth/idp/oauth/token` | +| Device Authorization | `https://sourcegraph.example.com/.auth/idp/oauth/device/code` | +| Token Revocation | `https://sourcegraph.example.com/.auth/idp/oauth/revoke` | +| Token Introspection | `https://sourcegraph.example.com/.auth/idp/oauth/introspect` | +| User Info | `https://sourcegraph.example.com/.auth/idp/oauth/userinfo` | + +## OAuth Flow Examples + + + +1. **Authorization Request**: Redirect users to Sourcegraph's authorization endpoint: + +```http +https://sourcegraph.example.com/.auth/idp/oauth/authorize? + response_type=code& + client_id=YOUR_CLIENT_ID& + redirect_uri=YOUR_REDIRECT_URI& + scope=user:all& + state=RANDOM_STATE_STRING +``` + +The user may be asked for consent to grant your app the requested scopes if not previously granted. + +2. **Authorization Response**: Sourcegraph redirects back with an authorization code and the state parameter: + +```http +https://your-app.com/callback? + code=AUTHORIZATION_CODE& + state=RANDOM_STATE_STRING +``` + +3. **Token Exchange**: Exchange the code for an access token: + +```bash +curl -X POST https://sourcegraph.example.com/.auth/idp/oauth/token \ + -H "Authorization: Basic $(echo -n 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' | base64)" \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "grant_type=authorization_code" \ + -d "code=AUTHORIZATION_CODE" \ + -d "redirect_uri=YOUR_REDIRECT_URI" +``` + +**Response:** + +```json +{ + "access_token": "ACCESS_TOKEN", + "token_type": "Bearer", + "expires_in": 3600, + "refresh_token": "REFRESH_TOKEN", + "scope": "user:all" +} +``` + + + + + +1. **Generate PKCE Parameters**: + +```javascript +// Generate code verifier (43-128 characters) +const codeVerifier = generateRandomString(128); + +// Create code challenge +const codeChallenge = base64URLEncode(sha256(codeVerifier)); +``` + +2. **Authorization Request**: + +```http +https://sourcegraph.example.com/.auth/idp/oauth/authorize? + response_type=code& + client_id=YOUR_CLIENT_ID& + redirect_uri=YOUR_REDIRECT_URI& + scope=user:all& + state=RANDOM_STATE_STRING& + code_challenge=CODE_CHALLENGE& + code_challenge_method=S256 +``` + +3. **Token Exchange**: + +```bash +curl -X POST https://sourcegraph.example.com/.auth/idp/oauth/token \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "grant_type=authorization_code" \ + -d "code=AUTHORIZATION_CODE" \ + -d "client_id=YOUR_CLIENT_ID" \ + -d "redirect_uri=YOUR_REDIRECT_URI" \ + -d "code_verifier=CODE_VERIFIER" +``` + +**Response:** + +```json +{ + "access_token": "ACCESS_TOKEN", + "token_type": "Bearer", + "expires_in": 3600, + "scope": "user:all" +} +``` + + + + + +For applications without a web browser or with limited input capabilities like a CLI or a portable device: + +1. **Device Authorization Request**: + +```bash +curl -X POST https://sourcegraph.example.com/.auth/idp/oauth/device/code \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "client_id=YOUR_CLIENT_ID" \ + -d "scope=user:all" +``` + +2. **Response:** + +```json +{ + "device_code": "DEVICE_CODE", + "user_code": "USER-CODE", + "verification_uri": "https://sourcegraph.example.com/device", + "verification_uri_complete": "https://sourcegraph.example.com/device?user_code=USER-CODE", + "expires_in": 1800, + "interval": 5 +} +``` + +3. **Poll for Token** (respect the `interval` field to avoid rate limiting): + +```bash +curl -X POST https://sourcegraph.example.com/.auth/idp/oauth/token \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "grant_type=urn:ietf:params:oauth:grant-type:device_code" \ + -d "client_id=YOUR_CLIENT_ID" \ + -d "device_code=DEVICE_CODE" +``` + +**Success Response:** + +```json +{ + "access_token": "ACCESS_TOKEN", + "token_type": "Bearer", + "expires_in": 3600, + "scope": "user:all" +} +``` + +**Pending Response** (continue polling): + +```json +{ + "error": "authorization_pending" +} +``` + + + + + +The client credentials flow is designed for server-to-server authentication without user interaction. Service accounts can create M2M (machine-to-machine) credentials that use this flow. You can create M2M credentials in the service account settings under **Access tokens > M2M credentials**. + +1. **Token Request** (no user interaction required): + +```bash +curl -X POST https://sourcegraph.example.com/.auth/idp/oauth/token \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "grant_type=client_credentials" \ + -d "client_id=YOUR_SERVICE_ACCT_CLIENT_ID" \ + -d "client_secret=YOUR_SERVICE_ACCT_CLIENT_SECRET" \ + -d "scope=user:all" +``` + +**Successful Response:** + +```json +{ + "access_token": "ACCESS_TOKEN", + "token_type": "Bearer", + "expires_in": 3600, + "scope": "user:all" +} +``` + +2. **Use the access token** exactly like any other OAuth bearer token: + +```bash +curl -H "Authorization: Bearer ACCESS_TOKEN" \ + -d '{"query": "query { currentUser { username } }"}' \ + https://sourcegraph.example.com/.api/graphql +``` + +Note: No refresh token is returned; just repeat the client-credentials call when the token expires (cache for `expires_in` seconds). + + + +## Using OAuth Tokens + +Once you have an OAuth access token, use it to authenticate API requests: + +### GraphQL API + +```bash +curl -H 'Authorization: Bearer YOUR_OAUTH_TOKEN' \ + -d '{"query": "query { currentUser { username } }"}' \ + https://sourcegraph.example.com/.api/graphql +``` + +### Streaming API + +```bash +curl -H 'Authorization: Bearer YOUR_OAUTH_TOKEN' \ + -H 'Accept: text/event-stream' \ + --get \ + --url 'https://sourcegraph.example.com/.api/search/stream' \ + --data-urlencode 'q=your search query' +``` + +## Token Management + +### Token Expiration + +OAuth access tokens issued by Sourcegraph are always short-lived with a fixed expiration time. Non-expiring access tokens are not available through the OAuth flow. Access tokens typically expire after 1 hour. + +### Refresh Tokens + +Refresh tokens are issued alongside every access token and must be used to obtain new access tokens before the current token expires: + +```bash +curl -X POST https://sourcegraph.example.com/.auth/idp/oauth/token \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "grant_type=refresh_token" \ + -d "refresh_token=YOUR_REFRESH_TOKEN" \ + -d "client_id=YOUR_CLIENT_ID" \ + -d "client_secret=YOUR_CLIENT_SECRET" # Only for private clients +``` + +**Important**: Always store the new refresh token returned in the response, as it may differ from the one you used in the request. + +### Token Expiration Handling + +Applications must proactively check token expiration and refresh tokens before they expire: + +1. **Monitor the `expires_in` field** from token responses to track when tokens expire +2. **Refresh proactively** by checking expiration time before each API call +3. **Use a safety buffer** of 60+ seconds to avoid race conditions +4. **Handle 401 responses** by refreshing the token and retrying the request + +### Token Revocation + +Users can revoke OAuth consents through their account settings, or your integration can programmatically revoke tokens: + +```bash +curl -X POST https://sourcegraph.example.com/.auth/idp/oauth/revoke \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "token=ACCESS_TOKEN_OR_REFRESH_TOKEN" \ + -d "token_type_hint=access_token" \ + -d "client_id=YOUR_CLIENT_ID" \ + -d "client_secret=YOUR_CLIENT_SECRET" # Only for private clients +``` diff --git a/docs/api/graphql/index.mdx b/docs/api/graphql/index.mdx index 1b8e88e0b..6d0b7925a 100644 --- a/docs/api/graphql/index.mdx +++ b/docs/api/graphql/index.mdx @@ -12,11 +12,11 @@ The Sourcegraph GraphQL API supports the following types of queries: ## Quickstart -Generate an access token on your Sourcegraph instance at: +There are two ways to authenticate with the Sourcegraph GraphQL API: -```none -https://sourcegraph.example.com/user/settings/tokens -``` +### Access Tokens + +Generate an access token for your Sourcegraph instance under **Settings > Access tokens**. Then run this query to echo your username back: @@ -26,12 +26,24 @@ curl -H 'Authorization: token YOUR_TOKEN' https://sourcegraph.example.com/.api/graphql ``` -You should see a response like this: +### OAuth Tokens + +If you have an [OAuth app](/admin/oauth_apps) configured with the `user:all` scope, you can use OAuth Bearer tokens: + +```bash +curl -H 'Authorization: Bearer YOUR_OAUTH_TOKEN' +-d '{"query": "query { currentUser { username } }"}' +https://sourcegraph.example.com/.api/graphql +``` + +Both authentication methods will return a response like this: ```json { "data": { "currentUser": { "username": "YOUR_USERNAME" } } } ``` +OAuth access tokens are always short-lived and must be refreshed using refresh tokens before expiration. Check the `expires_in` field and refresh proactively. + For automated scripts, CI/CD pipelines, and production integrations, use [service accounts](/admin/access_control/service_accounts) instead of personal access tokens. Service accounts are designed specifically for programmatic API access and provide better security and audit capabilities. ## Documentation & tooling diff --git a/docs/api/stream_api/index.mdx b/docs/api/stream_api/index.mdx index f0ce46a92..0168a99b5 100644 --- a/docs/api/stream_api/index.mdx +++ b/docs/api/stream_api/index.mdx @@ -13,6 +13,7 @@ putting pressure on the backend. ## Request ```bash +# Using access token curl --header "Accept: text/event-stream" \ --header "Authorization: token " \ --get \ @@ -24,11 +25,24 @@ curl --header "Accept: text/event-stream" \ --data-urlencode "cm=" \ --data-urlencode "display=" \ --data-urlencode "cl=" + +# Using OAuth token +curl --header "Accept: text/event-stream" \ + --header "Authorization: Bearer " \ + --get \ + --url "/.api/search/stream" \ + --data-urlencode "q=" \ + --data-urlencode "v=" \ + --data-urlencode "t=" \ + --data-urlencode "max-line-len=" \ + --data-urlencode "cm=" \ + --data-urlencode "display=" \ + --data-urlencode "cl=" ``` | Parameter | Description | |---------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| access token | [Sourcegraph access token](/cli/how-tos/creating_an_access_token) | +| access token / oauth token | [Sourcegraph access token](/cli/how-tos/creating_an_access_token) or [OAuth token](/admin/oauth_apps) with `user:all` scope. See [GraphQL API authentication](/api/graphql#quickstart) for details on token refresh and expiration handling. | | Sourcegraph URL | The URL of your Sourcegraph instance, or https://sourcegraph.com. | | query | A Sourcegraph query string, see our [search query syntax](/code-search/queries) | | version (optional) | The version of the search query syntax. We recommend to explicitly set the version. The latest version is "V3". (Default: "V3") | diff --git a/src/data/navigation.ts b/src/data/navigation.ts index d06a56582..9d9bffe08 100644 --- a/src/data/navigation.ts +++ b/src/data/navigation.ts @@ -455,6 +455,7 @@ export const navigation: NavigationItem[] = [ title: 'Repository Permissions', href: '/admin/permissions' }, + { title: 'OAuth Apps', href: '/admin/oauth_apps' }, { title: 'Analytics', href: '/admin/analytics' }, { title: 'Executors', href: '/admin/executors' }, { title: 'FAQs', href: '/admin/faq' }, From a60c2aec6911526a172362cc5dfa8c5771f2dddd Mon Sep 17 00:00:00 2001 From: Erik Seliger Date: Thu, 14 Aug 2025 19:54:58 +0200 Subject: [PATCH 2/6] SA redirect --- docs/admin/{access_control => }/service_accounts.mdx | 0 src/data/redirects.ts | 5 +++++ 2 files changed, 5 insertions(+) rename docs/admin/{access_control => }/service_accounts.mdx (100%) diff --git a/docs/admin/access_control/service_accounts.mdx b/docs/admin/service_accounts.mdx similarity index 100% rename from docs/admin/access_control/service_accounts.mdx rename to docs/admin/service_accounts.mdx diff --git a/src/data/redirects.ts b/src/data/redirects.ts index 8b4ac5ce4..890d1a02c 100644 --- a/src/data/redirects.ts +++ b/src/data/redirects.ts @@ -6928,6 +6928,11 @@ const redirectsData = [ destination: '/admin/http_https_configuration', permanent: true }, + { + source: '/admin/access_control/service_accounts', + destination: '/admin/service_accounts', + permanent: true + }, ]; const updatedRedirectsData = redirectsData.map(redirect => { From 55eb768f5e7be7c6a7dbb66ffd75cd23ecdb14e6 Mon Sep 17 00:00:00 2001 From: Erik Seliger Date: Thu, 14 Aug 2025 19:55:56 +0200 Subject: [PATCH 3/6] Fixups --- docs/admin/access_control/index.mdx | 2 +- docs/admin/auth/index.mdx | 2 +- docs/admin/oauth_apps.mdx | 2 +- docs/api/graphql/index.mdx | 2 +- public/llms.txt | 1063 ++++++++++++++++----------- 5 files changed, 633 insertions(+), 438 deletions(-) diff --git a/docs/admin/access_control/index.mdx b/docs/admin/access_control/index.mdx index c55bd36d7..011629002 100644 --- a/docs/admin/access_control/index.mdx +++ b/docs/admin/access_control/index.mdx @@ -40,7 +40,7 @@ You can read about the specific permission types available for each RBAC-enabled - [Batch Changes](/admin/access_control/batch_changes) - [Ownership](/admin/access_control/ownership) -- [Service accounts](/admin/access_control/service_accounts) +- [Service accounts](/admin/service_accounts) ### Deleting a role diff --git a/docs/admin/auth/index.mdx b/docs/admin/auth/index.mdx index d7abfa0c8..8da3abd89 100644 --- a/docs/admin/auth/index.mdx +++ b/docs/admin/auth/index.mdx @@ -31,7 +31,7 @@ The authentication providers are configured in the [`auth.providers`](/admin/con ## Programmatic authentication -For automated systems, CI/CD pipelines, and API integrations that need to authenticate without human interaction, use [service accounts](/admin/access_control/service_accounts). Service accounts are specialized user accounts designed for automation that authenticate using access tokens rather than passwords. +For automated systems, CI/CD pipelines, and API integrations that need to authenticate without human interaction, use [service accounts](/admin/service_accounts). Service accounts are specialized user accounts designed for automation that authenticate using access tokens rather than passwords. ## Login form configuration diff --git a/docs/admin/oauth_apps.mdx b/docs/admin/oauth_apps.mdx index 13a08a7dc..3c2031abf 100644 --- a/docs/admin/oauth_apps.mdx +++ b/docs/admin/oauth_apps.mdx @@ -11,7 +11,7 @@ This makes OAuth the preferred choice for any multi-user integration like browse OAuth Apps follow standards [RFC 6749](https://tools.ietf.org/html/rfc6749), [RFC 7636 (PKCE)](https://tools.ietf.org/html/rfc7636), and [RFC 8628 (Device Authorization Grant)](https://tools.ietf.org/html/rfc8628). -Consider using **M2M (client-credentials) service-account tokens** or traditional [access tokens](/admin/access_control/access_tokens) for server-to-server communication, automated scripts, CI/CD pipelines, or single-user applications that do not require per-user permission checks. See [service accounts](/admin/access_control/service_accounts#m2m-oauth-credentials-client-credentials-flow) for details. +Consider using **M2M (client-credentials) service-account tokens** or traditional [access tokens](/admin/access_control/access_tokens) for server-to-server communication, automated scripts, CI/CD pipelines, or single-user applications that do not require per-user permission checks. See [service accounts](/admin/service_accounts#m2m-oauth-credentials-client-credentials-flow) for details. ## Creating an OAuth App diff --git a/docs/api/graphql/index.mdx b/docs/api/graphql/index.mdx index 6d0b7925a..d0fa78538 100644 --- a/docs/api/graphql/index.mdx +++ b/docs/api/graphql/index.mdx @@ -44,7 +44,7 @@ Both authentication methods will return a response like this: OAuth access tokens are always short-lived and must be refreshed using refresh tokens before expiration. Check the `expires_in` field and refresh proactively. -For automated scripts, CI/CD pipelines, and production integrations, use [service accounts](/admin/access_control/service_accounts) instead of personal access tokens. Service accounts are designed specifically for programmatic API access and provide better security and audit capabilities. +For automated scripts, CI/CD pipelines, and production integrations, use [service accounts](/admin/service_accounts) instead of personal access tokens. Service accounts are designed specifically for programmatic API access and provide better security and audit capabilities. ## Documentation & tooling diff --git a/public/llms.txt b/public/llms.txt index 97feee713..9daed51c6 100644 --- a/public/llms.txt +++ b/public/llms.txt @@ -13,6 +13,7 @@ Currently supported versions of Sourcegraph: | **Release** | **General Availability Date** | **Supported** | **Release Notes** | **Install** | |--------------|-------------------------------|---------------|--------------------------------------------------------------------|------------------------------------------------------| +| 6.6 Patch 2 | August 2025 | ✅ | [Notes](https://sourcegraph.com/docs/technical-changelog#v662517) | [Install](https://sourcegraph.com/docs/admin/deploy) | | 6.6 Patch 1 | June 2025 | ✅ | [Notes](https://sourcegraph.com/docs/technical-changelog#v66868) | [Install](https://sourcegraph.com/docs/admin/deploy) | | 6.6 Patch 0 | June 2025 | ✅ | [Notes](https://sourcegraph.com/docs/technical-changelog#v660) | [Install](https://sourcegraph.com/docs/admin/deploy) | | 6.5 Patch 2 | June 2025 | ✅ | [Notes](https://sourcegraph.com/docs/technical-changelog#v652654) | [Install](https://sourcegraph.com/docs/admin/deploy) | @@ -232,7 +233,7 @@ If you have questions about anything related to Sourcegraph, you're always welco # Sourcegraph Tutorials -

Explore to learn more about Sourcegaph tutorials and guides.

+

Explore to learn more about Sourcegraph tutorials and guides.

## Find Your Way Around Sourcegraph @@ -1712,6 +1713,13 @@ Future updates will be distributed through the Firefox store and won't require a + +# JetBrains plugin + +- See user docs at [jetbrains/README](https://sourcegraph.com/github.com/sourcegraph/jetbrains/-/blob/README.md) + + + # Integrations @@ -1731,10 +1739,9 @@ Sourcegraph integrates with your other tools to help you search, navigate, and r - Launcher extensions - [Sourcegraph for Raycast](https://www.raycast.com/bobheadxi/sourcegraph) (unofficial): search code, browse notebooks, and manage batch changes from the Raycast launcher -- IDE Extensions +- Cody IDE Extensions - [JetBrains](/integration/jetbrains) - - [Manual testing](/integration/jetbrains/manual_testing) - - [VS Code](/integration/vscode) + - [VS Code](/cody/clients/install-vscode) ![GitHub pull request integration](https://storage.googleapis.com/sourcegraph-assets/code-graph/docs/github-pr.png) @@ -2125,179 +2132,6 @@ The [Sourcegraph browser extension](/integration/browser_extension) does not yet - -# VS Code extension - -- [See user docs](/cody/clients/install-vscode) - - - - - -# JetBrains plugin manual test cases - -## Overview - -All these test scripts are written in a way so that humans can perform it, but also an E2E testing tool can run it eventually. - -Each of these test cases should be run either right after starting the IDE and opening a project, _or_ after closing and reopening a project, to make sure we have a clean state. - -### Test case format anatomy - -* The numbered items are the steps to perform in order. -* The indented bullets are assertions. - -### Performing a test manually - -If a red error notification appears at the bottom right of the IDE, that means we have a problem. - -Same if any of the assertions fail. - -If there is a problem, we should either investigate right away (typically, if a developer does the manual testing), or create an issue with the error message / specifying which test case failed, and any additional helpful context. - -### Operating systems - -We test on macOS by default, but we should also test on Windows and Linux more often. -We have three test instances to test the plugin on a Linux server, an Ubuntu Desktop machine, and on Windows Server. They are all on GCP, [here](https://console.cloud.google.com/compute/instances?cloudshell=true&project=david-veszelovszki-temp-env). -- For the Windows instance, follow [this guide](https://www.snel.com/support/how-to-connect-to-your-server-via-rdp-on-macos/) to connect, then use the login/password you find in 1Password by the name "GCP: JetBrains plugin testing Windows". - -## Test cases - -### Website-related features - -#### Preparation - -**Perforce** testing is slightly tricky because we don’t currently have a lot of Perforce code hosts added to any of our Sourcegraph instances. Try this: - -* Use [https://cse-k8s.sgdev.org/](https://cse-k8s.sgdev.org/) as your Sourcegraph URL -* Generate an access token for yourself for CSE-K8S (admin user in 1Password), set that -* Set up a Perforce client -* Set `perforce-tests.sgdev.org:1666` for the port. User is “admin”, password is in 1Password. -* Make sure your connection work, and _actually connect_ in P4V (connection didn’t work without this step in IntelliJ for me) -* Create a workspace for yourself (delete an old one if you bump into the 20-workspace limit), and include the `test-large-depot` depot -* In the JetBrains plugin settings, set the replacement string to `perforce-tests.sgdev.org:,perforce.beatrix.com:app/,.perforce,/patch/core.perforce`. -* At this point, your files should open properly in your browser. - -#### Search Selection and Open/Copy features - -1. Open a project with a file that’s under Git version control -2. Right click on editor | Sourcegraph | Search Selection on Sourcegraph Web - * Make sure it searches the current selection in all repos -3. Right click on editor | Sourcegraph | Search Selection in Repository on Sourcegraph Web - * Make sure it searches the current selection in the current repo -4. Right click on editor | Sourcegraph | Open Selection in Sourcegraph Web - * Make sure it opens the right file on the web -5. Copy Sourcegraph File Link - * Make sure it copies the right URL (should be good if the previous point worked because they share the logic.) -6. Repeat it with a Perforce repo. - -#### “Open Revision Diff in Sourcegraph Web” - -1. Open a project that has files under Git version control -2. Open Version Control (⌘9) | Log -3. Right click on a commit and choose Open Revision Diff in Sourcegraph Web -4. Make sure the right page opens on the Sourcegraph instance set up in the plugin settings -5. (Would be cool to also test this each time with a project that has files from multiple repositories.) -6. Repeat the process with a project that has files under Perforce version control. - -### Find with Sourcegraph - -#### Popup opens, loads, and closes - -Why: To make sure the popup is discoverable and generally works - -1. Press the shortcut for the popup - * The popup should become active - * The popup should be in the “loading” state -2. Wait until the “loading” state is gone - * It should not take more than ~five seconds -3. Close the popup with ESC - * The popup should become hidden -4. Open “Find Action” (⌘⇧A) and search for “find with sourcegraph” and select the first result - * The popup should become active - * The popup should not be in the “loading” state -5. Click the header of the IDE main window - * The popup should become hidden -6. In the main menu, choose Edit | Find | Find on Sourcegraph… - * The popup should become active - -#### Browser doesn’t disappear after a few opens - -Why: After opening and closing the "Find on Sourcegraph" popup four-five times on Mac, the browser disappears if _circumstances are not right_. This bug should be fixed, but it may reappear if we mess something up. - -1. Open popup with the shortcut - * The popup should become active -2. Wait until the “loading” state is gone -3. Close the popup with ESC -4. Open popup with the shortcut - * The popup should become active, and the browser should be visible -5. Repeat 3–4 at least five times. - -#### Search results are displayed and navigation works - -Why: To make sure that the most basic functionality of the popup works - -1. Open the popup with the shortcut -2. Wait for the browser content to load -3. Type “repo:^github\.com/sourcegraph/sourcegraph file:index.ts” - * It should type into the input box - * The content should be exactly the same as what was typed -4. Press Enter -5. Wait for the search results and preview to load - * The result list and the preview box should populate -6. Press `↓` key -7. Wait for the search results and preview to load - * The preview should be different from the previous one -8. Press `⌥Enter` - * The popup should close - * A new editor tab should open - * The content of the new tab should be the same as the last preview -9. Open the popup with the shortcut -10. Press ⌘A, type “repo:^github\.com/sourcegraph/sourcegraph” and press Enter -11. Wait for the search results to load - * The result list should update - * The preview state should be “No preview available” -12. Press ⌥Enter - * The popup should close - * A browser should open (if automated: an “open browser” trigger should be sent) - -#### Server connection success/failure is recognized - -This test needs a valid access token that can be generated at https://sourcegraph.com/users/{username}/settings/tokens - -* Open Settings with `⌘`, -* Go to Tools | Sourcegraph -* Set the URL to “[https://sourcegraph.com](https://sourcegraph.com)” -* Set the access token to a valid one - * Press Enter to save settings -* Open the popup with the shortcut -* Wait for the browser content to load. - * The search box should be visible -* Close the popup with ESC -* Open Settings with ⌘, -* Type “TEST” after the end of the valid access token. -* Press Enter to save settings -* Open the popup with the shortcut - * The search box should not be visible, an error message should appear - * The preview should be saying “No preview available” -* Close the popup with ESC -* Open Settings with ⌘, -* Remove “TEST” to again have the valid access token. -* Press Enter to save settings -* Open the popup with the shortcut - * The search box should be visible again. - - - - -# JetBrains plugin - -- See user docs at [jetbrains/README](https://sourcegraph.com/github.com/sourcegraph/jetbrains/-/tree/README) -- See dev docs at [jetbrains/CONTRIBUTING](https://sourcegraph.com/github.com/sourcegraph/jetbrains/-/tree/CONTRIBUTING) -- [Manual test cases](/integration/jetbrains/manual_testing) - - - # Quickstart for Browser Extensions @@ -8012,8 +7846,8 @@ Cody supports a variety of cutting-edge large language models for use in chat an | Google | [Gemini 1.5 Pro](https://deepmind.google/technologies/gemini/pro/) | ✅ (beta) | | Google | [Gemini 2.0 Flash](https://deepmind.google/technologies/gemini/flash/) | ✅ | | Google | [Gemini 2.0 Flash](https://deepmind.google/technologies/gemini/flash/) | ✅ | -| Google | [Gemini 2.5 Pro Preview](https://cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/2-5-pro) | ✅ | -| Google | [Gemini 2.5 Flash Preview](https://cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/2-5-flash) | ✅ (experimental) | +| Google | [Gemini 2.5 Pro](https://cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/2-5-pro) | ✅ | +| Google | [Gemini 2.5 Flash](https://cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/2-5-flash) | ✅ | To use Claude 3 Sonnet models with Cody Enterprise, make sure you've upgraded your Sourcegraph instance to the latest version. @@ -25932,6 +25766,7 @@ putting pressure on the backend. ## Request ```bash +# Using access token curl --header "Accept: text/event-stream" \ --header "Authorization: token " \ --get \ @@ -25943,11 +25778,24 @@ curl --header "Accept: text/event-stream" \ --data-urlencode "cm=" \ --data-urlencode "display=" \ --data-urlencode "cl=" + +# Using OAuth token +curl --header "Accept: text/event-stream" \ + --header "Authorization: Bearer " \ + --get \ + --url "/.api/search/stream" \ + --data-urlencode "q=" \ + --data-urlencode "v=" \ + --data-urlencode "t=" \ + --data-urlencode "max-line-len=" \ + --data-urlencode "cm=" \ + --data-urlencode "display=" \ + --data-urlencode "cl=" ``` | Parameter | Description | |---------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| access token | [Sourcegraph access token](/cli/how-tos/creating_an_access_token) | +| access token / oauth token | [Sourcegraph access token](/cli/how-tos/creating_an_access_token) or [OAuth token](/admin/oauth_apps) with `user:all` scope. See [GraphQL API authentication](/api/graphql#quickstart) for details on token refresh and expiration handling. | | Sourcegraph URL | The URL of your Sourcegraph instance, or https://sourcegraph.com. | | query | A Sourcegraph query string, see our [search query syntax](/code-search/queries) | | version (optional) | The version of the search query syntax. We recommend to explicitly set the version. The latest version is "V3". (Default: "V3") | @@ -26657,11 +26505,11 @@ The Sourcegraph GraphQL API supports the following types of queries: ## Quickstart -Generate an access token on your Sourcegraph instance at: +There are two ways to authenticate with the Sourcegraph GraphQL API: -```none -https://sourcegraph.example.com/user/settings/tokens -``` +### Access Tokens + +Generate an access token for your Sourcegraph instance under **Settings > Access tokens**. Then run this query to echo your username back: @@ -26671,13 +26519,25 @@ curl -H 'Authorization: token YOUR_TOKEN' https://sourcegraph.example.com/.api/graphql ``` -You should see a response like this: +### OAuth Tokens + +If you have an [OAuth app](/admin/oauth_apps) configured with the `user:all` scope, you can use OAuth Bearer tokens: + +```bash +curl -H 'Authorization: Bearer YOUR_OAUTH_TOKEN' +-d '{"query": "query { currentUser { username } }"}' +https://sourcegraph.example.com/.api/graphql +``` + +Both authentication methods will return a response like this: ```json { "data": { "currentUser": { "username": "YOUR_USERNAME" } } } ``` -For automated scripts, CI/CD pipelines, and production integrations, use [service accounts](/admin/access_control/service_accounts) instead of personal access tokens. Service accounts are designed specifically for programmatic API access and provide better security and audit capabilities. +OAuth access tokens are always short-lived and must be refreshed using refresh tokens before expiration. Check the `expires_in` field and refresh proactively. + +For automated scripts, CI/CD pipelines, and production integrations, use [service accounts](/admin/service_accounts) instead of personal access tokens. Service accounts are designed specifically for programmatic API access and provide better security and audit capabilities. ## Documentation & tooling @@ -27025,102 +26885,7 @@ The Sourcegraph Analytics API is an API that provides programmatic access to you For Sourcegraph Analytics, you can generate an access token for programmatic access. Tokens are long-lived with an optional expiry and have the same permissions to access instance data as the user who created them. -### Getting Started - -Access tokens are created using the `cas` cookie for authentication to the token creation endpoint. Access tokens are longer lived than the `cas` cookie making them more suitable for programmatic access to the Sourcegraph Analytics API. - -- Sign in to [Sourcegraph Analytics](https://analytics.sourcegraph.com). -- Retrieve your session cookie, `cas`, from your browser's developer tools. - -![Sourcegraph Analytics session cookie](https://storage.googleapis.com/sourcegraph-assets/Docs/analytics-cookie.png) - -- Export the cookie as an environment variable to use in the following commands: - -```sh -export CAS_COOKIE="" -``` - -#### Token creation - -Create the token by running the following command: - -```sh -curl -X POST https://analytics.sourcegraph.com/api/service-access-tokens \ - -H "Content-Type: application/json" \ - -H "Cookie: cas=$CAS_COOKIE" \ - -d '{}' - -# Optionally include displayName, expiresAt, or both in the request body. -# If expiresAt is not provided, the token will never expire and must be revoked manually. -# -d '{"displayName": "My Analytics Token", "expiresAt": "2025-12-31T23:59:59Z"}' -``` - -The response will include the token ID, secret, creation date, and, if provided, display name and expiration date. For example: - -```json -{ - "id": "4cf96e80-d5f3-4af0-a28d-3c70ba97abb4", - "displayName": "My Analytics Token", - "secret": "sams_at_abcdefghijk", - "createdAt": "2025-05-28T12:00:00Z", - "expiresAt": "2025-12-31T23:59:59Z" -} -``` - -#### Token listing - -List the tokens by running the following command: - -```sh -curl -X GET https://analytics.sourcegraph.com/api/service-access-tokens \ - -H "Cookie: cas=$CAS_COOKIE" -``` - -Each token in the response will include the token ID, creation date, a boolean indicating if the token has expired, and display name and expiration date if provided. For example: - -```json -{ - "tokens": [ - { - "id": "5a140b00-3a79-497d-bcfb-c1d2e3d8c747", - "displayName": "My Analytics Token", - "createdAt": "2025-05-27T12:00:00Z", - "expiresAt": "2025-05-27T13:00:00Z", - "isExpired": true - }, - { - "id": "eaf8a6f1-1302-43f6-a9ad-f9862d75e959", - "createdAt": "2025-05-28T12:30:00Z", - "expiresAt": "2025-05-28T13:30:00Z", - "isExpired": true - }, - { - "id": "d7df6636-99d0-4266-9f32-a2fb7ccbfcd5", - "displayName": "My Analytics Token 2", - "createdAt": "2025-05-28T15:00:00Z", - "isExpired": false - }, - { - "id": "8ea63000-a164-44ca-8834-bb71e9b788fb", - "createdAt": "2025-05-28T15:30:00Z", - "isExpired": false - } - ] -} -``` - -#### Token revocation - -Revoke a token by running the following commands: - -```sh -export TOKEN_ID="" - -curl -X DELETE https://analytics.sourcegraph.com/api/service-access-tokens/$TOKEN_ID \ - -H "Cookie: cas=$CAS_COOKIE" -``` - -The revocation request does not produce output. To verify that a token has been revoked, list the tokens and verify that `isExpired` is `true`. +To get started, visit the [Sourcegraph Analytics access tokens management page](http://analytics.sourcegraph.com/access-tokens). From here, you can create, view, and revoke access tokens for your Sourcegraph Account. ## API reference @@ -27943,6 +27708,180 @@ B-->|HTTP request: 7080|C + +# Service Accounts + +Service accounts are specialized user accounts designed for automation, API integrations, and programmatic access to Sourcegraph, as opposed to using access tokens from regular users. Unlike regular user accounts, service accounts don't require an email address or password, cannot access the Sourcegraph UI, don't count towards a license's user limit and won't be part of any billing cycles. + +## Creating Service Accounts + +Service accounts are created like regular user accounts, but with a few key differences. + +- Go to **Site admin** → **Users & auth** → **Users** +- Click **Create User** +- Enter a descriptive **Username** (e.g., `ci-bot-scip-uploads`, `api-search-jobs`) +- Check the **Service account** checkbox +- Click **Create service account** + +![create-service-account](https://storage.googleapis.com/sourcegraph-assets/Docs/create-service-accounts-0625.png) + +You'll be presented with some next steps you might want to take, like creating an access token, managing and assigning roles, and managing repository permissions. + +- Service accounts are automatically assigned the "Service Account" system role +- They appear in the user list with "Service account" type designation +- By default, service accounts can only access public and unrestricted repositories + +![next-steps-service-account](https://storage.googleapis.com/sourcegraph-assets/Docs/service-accounts-next-steps-0625.png) + +## Managing Access Tokens + +Service accounts can authenticate using either traditional access tokens or M2M (machine-to-machine) OAuth credentials. + +### Traditional Access Tokens + +For detailed information about creating, managing, and using traditional access tokens, see: + +- [Creating an access token](/cli/how-tos/creating_an_access_token) +- [Managing access tokens](/cli/how-tos/managing_access_tokens) +- [Revoking an access token](/cli/how-tos/revoking_an_access_token) + +### M2M OAuth Credentials (Client Credentials Flow) + +M2M credentials provide short-lived tokens via the OAuth client credentials flow expiring after 1 hour. + +**Creating M2M credentials:** + +1. Navigate to the service account's user settings +2. Go to **Access tokens** → **M2M credentials** +3. Click **Create M2M credential** +4. Provide a descriptive **Name** and optional **Description** +5. Select scopes +6. Click **Create** to generate client credentials (client ID and secret) + +**Important:** Store the client secret securely - it won't be displayed again after creation. + +**Using M2M credentials:** + +```bash +# Get an access token using client credentials +curl -X POST https://sourcegraph.example.com/.auth/idp/oauth/token \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "grant_type=client_credentials" \ + -d "client_id=YOUR_CLIENT_ID" \ + -d "client_secret=YOUR_CLIENT_SECRET" \ + -d "scope=user:all" + +# Use the returned access_token for API calls +curl -H "Authorization: Bearer ACCESS_TOKEN" \ + https://sourcegraph.example.com/.api/graphql +``` + +See [OAuth Apps → Client Credentials Flow](/admin/oauth_apps#oauth-flow-examples) for more details on the client credentials flow. + +Both authentication methods can be used to access Sourcegraph's [GraphQL API](/api/graphql) and [Stream API](/api/stream_api). + +## Role-Based Access Control (RBAC) + +Service accounts integrate with Sourcegraph's [role-based access control](/admin/access_control) to provide fine-grained permission control. + +### System Roles + +Service accounts are automatically assigned the **Service Account** system role, which provides basic API access permissions and standard search capabilities. The **Service Account** system role is applied to all service accounts and can be used to provide service accounts with a default set of permissions. For more specialized service accounts, it is recommended to create custom roles and assign them to service accounts as needed. + +### Managing Roles + +Administrators can assign additional roles to service accounts through the user management interface. For detailed information on managing roles and permissions, see: + +- [Managing roles and permissions](/admin/access_control#managing-roles-and-permissions) +- [Managing user roles](/admin/access_control#managing-user-roles) +- [Creating custom roles](/admin/access_control#creating-a-new-role-and-assigning-it-permissions) + +![service-account-roles](https://storage.googleapis.com/sourcegraph-assets/Docs/service-accounts-manage-roles-0625.png) + +## Repository Permissions + +Service accounts respect repository permissions and access controls. For comprehensive information about repository permissions, see the [Repository permissions](/admin/permissions) documentation. + +Service accounts by default can only access public and unrestricted repositories in Sourcegraph. You may explicitly grant fine-grained access to private repositories from the service account's user settings page, under the **Repo permissions** tab, or via [the GraphQL API](/admin/permissions/api#explicit-permissions-api). In the **Repo permissions** tab, you can also grant service accounts access to all current and future repositories on Sourcegraph, regardless of their visibility, which is useful for service accounts that need to do things like perform search jobs, but admins should take care to ensure that the access tokens for these accounts are not shared with unauthorized users. + +![service-account-repo-permissions](https://storage.googleapis.com/sourcegraph-assets/Docs/service-accounts-repo-permissions-0625.png) + + + + +# Administration + + + Supported on [Enterprise](/pricing/enterprise) plans. + + Available via the Web app. + + + +Sourcegraph administration is primarily managed by site administrators, who are responsible for the deployment, management, and configuration of Sourcegraph instances for end users. For a comprehensive introduction to site administration, refer to our [quickstart guide](/admin/how-to/site-admin-quickstart). + + +## [Deploy Sourcegraph](/admin/deploy) + +Get started running Sourcegraph on-prem. + +- [Deployment overview](/admin/deploy/) +- [Best practices](/admin/deployment_best_practices) +- [Validate a Sourcegraph deployment](/admin/validation) (experimental) + +## [Upgrade Sourcegraph](/admin/updates) + +- [Upgrade Overview](/admin/updates/) +- [Migrate to Sourcegraph](/admin/migration/) +- [Upgrading PostgreSQL](/admin/postgres#upgrading-postgresql) + +## [Configure Sourcegraph](/admin/config) + +- [Site Administrator Quickstart](/admin/how-to/site-admin-quickstart) +- [Integrations](/integration/) +- [Add Git repositories](/admin/repo/add) (from a code host or clone URL) + - [Monorepo](/admin/monorepo) + - [Repository webhooks](/admin/repo/webhooks) +- [HTTP and HTTPS/SSL configuration](/admin/http_https_configuration) + - [Adding SSL (HTTPS) to Sourcegraph with a self-signed certificate](/admin/ssl_https_self_signed_cert_nginx) +- [User authentication](/admin/auth/) + - [User data deletion](/admin/user_data_deletion) +- [Provision users through SCIM](/admin/scim) (Beta) +- [Access control](/admin/access_control/) (Beta) +- [Setting the URL for your instance](/admin/url) +- [Repository permissions](/admin/permissions/) +- [Batch Changes](/batch-changes/site-admin-configuration) +- [Configure webhooks](/admin/config/webhooks/) +- [Scaling workers](/admin/workers) +- [PostgreSQL configuration](/admin/config/postgres-conf) + +## [Observability](/admin/observability) + +- [Monitoring guide](/admin/how-to/monitoring-guide) +- [Metrics and dashboards](/admin/observability/metrics) +- [Alerting](/admin/observability/alerting) +- [Tracing](/admin/observability/tracing) +- [Logs](/admin/observability/logs) +- [Outbound request log](/admin/observability/outbound-request-log) +- [OpenTelemetry](/admin/observability/opentelemetry) +- [Health checks](/admin/observability/health_checks) +- [Troubleshooting guide](/admin/observability/troubleshooting) + +## Features + +- [Analytics](/admin/analytics) (experimental) +- [Batch Changes](/batch-changes/) +- [Beta and experimental features](/admin/beta_and_experimental_features) +- [Code navigation](/code-search/code-navigation/) +- [Pings](/admin/pings) +- [Enterprise pricing and licenses](/admin/subscriptions/) +- [Search](/admin/search) +- [Usage statistics](/admin/usage_statistics) +- [User feedback surveys](/admin/user_surveys) +- [Audit logs](/admin/audit_log) + + + # Security Event Logs @@ -29204,6 +29143,362 @@ To automatically join all users on your instance to a specific organization, cre + +# OAuth Apps + +OAuth Apps let you build rich third-party experiences that call Sourcegraph **on behalf of end-users while honoring their repository permissions**. Every API request made with an OAuth access token is evaluated against the same authorization rules that apply inside the Sourcegraph UI, so your integration only sees the code each user is allowed to see. + +This makes OAuth the preferred choice for any multi-user integration like browser extensions, IDE plugins, chatbots, internal tools, or SaaS platforms where you need to: + +- Authenticate users with familiar Sourcegraph credentials +- Operate without ever handling or storing users' passwords +- Rely on short-lived, scoped tokens that can be revoked at any time +- Guarantee that repository visibility and other access controls are enforced automatically + +OAuth Apps follow standards [RFC 6749](https://tools.ietf.org/html/rfc6749), [RFC 7636 (PKCE)](https://tools.ietf.org/html/rfc7636), and [RFC 8628 (Device Authorization Grant)](https://tools.ietf.org/html/rfc8628). + +Consider using **M2M (client-credentials) service-account tokens** or traditional [access tokens](/admin/access_control/access_tokens) for server-to-server communication, automated scripts, CI/CD pipelines, or single-user applications that do not require per-user permission checks. See [service accounts](/admin/service_accounts#m2m-oauth-credentials-client-credentials-flow) for details. + +## Creating an OAuth App + +Site admins can create OAuth Apps in the site admin area: + +1. Navigate to **Site admin > OAuth clients** +2. Click **Create OAuth client** +3. Provide the following information: + - **Name**: A descriptive name for your application + - **Description**: (Optional) Additional details about the app's purpose + - **Redirect URI**: The URL where users will be redirected after authorization + - **Client type**: Choose between **Public** or **Private** + - **Scopes**: Select the permissions your app needs + +4. Click **Create** to generate the OAuth client + +After creation, you'll receive: + +- **Client ID**: Public identifier for your application +- **Client Secret**: (Private clients only) Secret key for authentication + +Store the client secret securely. It won't be displayed again after initial creation. + +## Client Types + +### Public Clients + +Public clients are designed for applications that cannot securely store client secrets: + +- **Browser-based applications** (SPAs) +- **Mobile applications** +- **Desktop applications** + +Public clients: + +- Do not receive a client secret +- Must use PKCE (Proof Key for Code Exchange) for security +- Support RFC 8628 Device Authorization Grant flow +- Are suitable for environments where the client code is publicly accessible + +### Private Clients + +Private clients can securely store client secrets: + +- **Server-side web applications** +- **Backend services** +- **Secure server environments** + +Private clients: + +- Receive both client ID and client secret +- Can use the standard authorization code flow (PKCE strongly recommended) +- Allow client authentication with a secret and server-side code exchange + +## Available Scopes + +When creating an OAuth app, select the minimum scopes necessary for your application: + +| Scope | Description | +|-------|-------------| +| `openid` | Required for OpenID Connect authentication | +| `profile` | Access to user profile information (name, picture, etc.) | +| `email` | Access to user's email address | +| `offline_access` | Request refresh tokens for offline access | +| `user:all` | Full access to Sourcegraph API on behalf of the user | + +The `user:all` scope is required for GraphQL API access with OAuth tokens. + +## OAuth endpoints reference + +| Endpoint | URL | +|----------|-----| +| Authorization | `https://sourcegraph.example.com/.auth/idp/oauth/authorize` | +| Token | `https://sourcegraph.example.com/.auth/idp/oauth/token` | +| Device Authorization | `https://sourcegraph.example.com/.auth/idp/oauth/device/code` | +| Token Revocation | `https://sourcegraph.example.com/.auth/idp/oauth/revoke` | +| Token Introspection | `https://sourcegraph.example.com/.auth/idp/oauth/introspect` | +| User Info | `https://sourcegraph.example.com/.auth/idp/oauth/userinfo` | + +## OAuth Flow Examples + + + +1. **Authorization Request**: Redirect users to Sourcegraph's authorization endpoint: + +```http +https://sourcegraph.example.com/.auth/idp/oauth/authorize? + response_type=code& + client_id=YOUR_CLIENT_ID& + redirect_uri=YOUR_REDIRECT_URI& + scope=user:all& + state=RANDOM_STATE_STRING +``` + +The user may be asked for consent to grant your app the requested scopes if not previously granted. + +2. **Authorization Response**: Sourcegraph redirects back with an authorization code and the state parameter: + +```http +https://your-app.com/callback? + code=AUTHORIZATION_CODE& + state=RANDOM_STATE_STRING +``` + +3. **Token Exchange**: Exchange the code for an access token: + +```bash +curl -X POST https://sourcegraph.example.com/.auth/idp/oauth/token \ + -H "Authorization: Basic $(echo -n 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' | base64)" \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "grant_type=authorization_code" \ + -d "code=AUTHORIZATION_CODE" \ + -d "redirect_uri=YOUR_REDIRECT_URI" +``` + +**Response:** + +```json +{ + "access_token": "ACCESS_TOKEN", + "token_type": "Bearer", + "expires_in": 3600, + "refresh_token": "REFRESH_TOKEN", + "scope": "user:all" +} +``` + + + + + +1. **Generate PKCE Parameters**: + +```javascript +// Generate code verifier (43-128 characters) +const codeVerifier = generateRandomString(128); + +// Create code challenge +const codeChallenge = base64URLEncode(sha256(codeVerifier)); +``` + +2. **Authorization Request**: + +```http +https://sourcegraph.example.com/.auth/idp/oauth/authorize? + response_type=code& + client_id=YOUR_CLIENT_ID& + redirect_uri=YOUR_REDIRECT_URI& + scope=user:all& + state=RANDOM_STATE_STRING& + code_challenge=CODE_CHALLENGE& + code_challenge_method=S256 +``` + +3. **Token Exchange**: + +```bash +curl -X POST https://sourcegraph.example.com/.auth/idp/oauth/token \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "grant_type=authorization_code" \ + -d "code=AUTHORIZATION_CODE" \ + -d "client_id=YOUR_CLIENT_ID" \ + -d "redirect_uri=YOUR_REDIRECT_URI" \ + -d "code_verifier=CODE_VERIFIER" +``` + +**Response:** + +```json +{ + "access_token": "ACCESS_TOKEN", + "token_type": "Bearer", + "expires_in": 3600, + "scope": "user:all" +} +``` + + + + + +For applications without a web browser or with limited input capabilities like a CLI or a portable device: + +1. **Device Authorization Request**: + +```bash +curl -X POST https://sourcegraph.example.com/.auth/idp/oauth/device/code \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "client_id=YOUR_CLIENT_ID" \ + -d "scope=user:all" +``` + +2. **Response:** + +```json +{ + "device_code": "DEVICE_CODE", + "user_code": "USER-CODE", + "verification_uri": "https://sourcegraph.example.com/device", + "verification_uri_complete": "https://sourcegraph.example.com/device?user_code=USER-CODE", + "expires_in": 1800, + "interval": 5 +} +``` + +3. **Poll for Token** (respect the `interval` field to avoid rate limiting): + +```bash +curl -X POST https://sourcegraph.example.com/.auth/idp/oauth/token \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "grant_type=urn:ietf:params:oauth:grant-type:device_code" \ + -d "client_id=YOUR_CLIENT_ID" \ + -d "device_code=DEVICE_CODE" +``` + +**Success Response:** + +```json +{ + "access_token": "ACCESS_TOKEN", + "token_type": "Bearer", + "expires_in": 3600, + "scope": "user:all" +} +``` + +**Pending Response** (continue polling): + +```json +{ + "error": "authorization_pending" +} +``` + + + + + +The client credentials flow is designed for server-to-server authentication without user interaction. Service accounts can create M2M (machine-to-machine) credentials that use this flow. You can create M2M credentials in the service account settings under **Access tokens > M2M credentials**. + +1. **Token Request** (no user interaction required): + +```bash +curl -X POST https://sourcegraph.example.com/.auth/idp/oauth/token \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "grant_type=client_credentials" \ + -d "client_id=YOUR_SERVICE_ACCT_CLIENT_ID" \ + -d "client_secret=YOUR_SERVICE_ACCT_CLIENT_SECRET" \ + -d "scope=user:all" +``` + +**Successful Response:** + +```json +{ + "access_token": "ACCESS_TOKEN", + "token_type": "Bearer", + "expires_in": 3600, + "scope": "user:all" +} +``` + +2. **Use the access token** exactly like any other OAuth bearer token: + +```bash +curl -H "Authorization: Bearer ACCESS_TOKEN" \ + -d '{"query": "query { currentUser { username } }"}' \ + https://sourcegraph.example.com/.api/graphql +``` + +Note: No refresh token is returned; just repeat the client-credentials call when the token expires (cache for `expires_in` seconds). + + + +## Using OAuth Tokens + +Once you have an OAuth access token, use it to authenticate API requests: + +### GraphQL API + +```bash +curl -H 'Authorization: Bearer YOUR_OAUTH_TOKEN' \ + -d '{"query": "query { currentUser { username } }"}' \ + https://sourcegraph.example.com/.api/graphql +``` + +### Streaming API + +```bash +curl -H 'Authorization: Bearer YOUR_OAUTH_TOKEN' \ + -H 'Accept: text/event-stream' \ + --get \ + --url 'https://sourcegraph.example.com/.api/search/stream' \ + --data-urlencode 'q=your search query' +``` + +## Token Management + +### Token Expiration + +OAuth access tokens issued by Sourcegraph are always short-lived with a fixed expiration time. Non-expiring access tokens are not available through the OAuth flow. Access tokens typically expire after 1 hour. + +### Refresh Tokens + +Refresh tokens are issued alongside every access token and must be used to obtain new access tokens before the current token expires: + +```bash +curl -X POST https://sourcegraph.example.com/.auth/idp/oauth/token \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "grant_type=refresh_token" \ + -d "refresh_token=YOUR_REFRESH_TOKEN" \ + -d "client_id=YOUR_CLIENT_ID" \ + -d "client_secret=YOUR_CLIENT_SECRET" # Only for private clients +``` + +**Important**: Always store the new refresh token returned in the response, as it may differ from the one you used in the request. + +### Token Expiration Handling + +Applications must proactively check token expiration and refresh tokens before they expire: + +1. **Monitor the `expires_in` field** from token responses to track when tokens expire +2. **Refresh proactively** by checking expiration time before each API call +3. **Use a safety buffer** of 60+ seconds to avoid race conditions +4. **Handle 401 responses** by refreshing the token and retrying the request + +### Token Revocation + +Users can revoke OAuth consents through their account settings, or your integration can programmatically revoke tokens: + +```bash +curl -X POST https://sourcegraph.example.com/.auth/idp/oauth/revoke \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "token=ACCESS_TOKEN_OR_REFRESH_TOKEN" \ + -d "token_type_hint=access_token" \ + -d "client_id=YOUR_CLIENT_ID" \ + -d "client_secret=YOUR_CLIENT_SECRET" # Only for private clients +``` + + + # Using Sourcegraph with a monorepo @@ -29268,22 +29563,7 @@ Sourcegraph uses [GitHub Flavored Markdown (GFM)](https://github.github.com/gfm/ -Sourcegraph administration is primarily managed by site administrators, who are responsible for the deployment, management, and configuration of Sourcegraph instances for end users. For a comprehensive introduction to site administration, refer to our [quickstart guide](/admin/how-to/site-admin-quickstart). - - -## [Deploy Sourcegraph](/admin/deploy/) - -Get started running Sourcegraph on-prem. - -- [Deployment overview](/admin/deploy/) -- [Best practices](/admin/deployment_best_practices) -- [Validate a Sourcegraph deployment](/admin/validation) (experimental) - -## [Upgrade Sourcegraph](/admin/updates/) - -- [Upgrade Overview](/admin/updates/) -- [Migrate to Sourcegraph](/admin/migration/) -- [Upgrading PostgreSQL](/admin/postgres#upgrading-postgresql) +Sourcegraph administration is primarily managed by site administrators, who are responsible for the configuration of Sourcegraph instances for end users. For a comprehensive introduction to site administration, refer to our [quickstart guide](/admin/how-to/site-admin-quickstart). ## [Configure Sourcegraph](/admin/config/) @@ -29292,30 +29572,13 @@ Get started running Sourcegraph on-prem. - [Add Git repositories](/admin/repo/add) (from a code host or clone URL) - [Monorepo](/admin/monorepo) - [Repository webhooks](/admin/repo/webhooks) -- [HTTP and HTTPS/SSL configuration](/admin/http_https_configuration) - - [Adding SSL (HTTPS) to Sourcegraph with a self-signed certificate](/admin/ssl_https_self_signed_cert_nginx) - [User authentication](/admin/auth/) - [User data deletion](/admin/user_data_deletion) - [Provision users through SCIM](/admin/scim) (Beta) - [Access control](/admin/access_control/) (Beta) -- [Setting the URL for your instance](/admin/url) - [Repository permissions](/admin/permissions/) - [Batch Changes](/batch-changes/site-admin-configuration) - [Configure webhooks](/admin/config/webhooks/) -- [Scaling workers](/admin/workers) -- [PostgreSQL configuration](/admin/config/postgres-conf) - -## [Observability](/admin/observability) - -- [Monitoring guide](/admin/how-to/monitoring-guide) -- [Metrics and dashboards](/admin/observability/metrics) -- [Alerting](/admin/observability/alerting) -- [Tracing](/admin/observability/tracing) -- [Logs](/admin/observability/logs) -- [Outbound request log](/admin/observability/outbound-request-log) -- [OpenTelemetry](/admin/observability/opentelemetry) -- [Health checks](/admin/observability/health_checks) -- [Troubleshooting guide](/admin/observability/troubleshooting) ## Features @@ -33184,7 +33447,7 @@ With this setting, Sourcegraph will ignore any rules with a host other than `*`, {/* SCHEMA_SYNC_START: admin/code_hosts/perforce.schema.json */} {/* WARNING: This section is auto-generated during releases. Do not edit manually. */} -{/* Last updated: 2025-07-28T21:25:40Z via sourcegraph/sourcegraph@v6.6.868 */} +{/* Last updated: 2025-08-07T02:20:49Z via sourcegraph/sourcegraph@v6.6.2517 */} ```json { // If non-null, enforces Perforce depot permissions. @@ -91515,7 +91778,7 @@ patches: You can update environment variables for **searcher** with `patches`. -For example, to update the value for `SEARCHER_CACHE_SIZE_MB` and `SEARCHER_CACHE_SIZE_MB`: +For example, to update the value for `SEARCHER_CACHE_SIZE_MB` and `SYMBOLS_CACHE_SIZE_MB`: ```yaml # instances/$INSTANCE_NAME/kustomization.yaml @@ -91529,7 +91792,7 @@ For example, to update the value for `SEARCHER_CACHE_SIZE_MB` and `SEARCHER_CACH value: name: SEARCHER_CACHE_SIZE_MB value: "50000" - - op: replace + - op: add path: /spec/template/spec/containers/0/env/0 value: name: SYMBOLS_CACHE_SIZE_MB @@ -95022,7 +95285,7 @@ All site configuration options and their default values are shown below. {/* SCHEMA_SYNC_START: admin/config/site.schema.json */} {/* WARNING: This section is auto-generated during releases. Do not edit manually. */} -{/* Last updated: 2025-07-28T21:25:28Z via sourcegraph/sourcegraph@v6.6.868 */} +{/* Last updated: 2025-08-07T02:20:38Z via sourcegraph/sourcegraph@v6.6.2517 */} ```json { @@ -96252,6 +96515,7 @@ All site configuration options and their default values are shown below. } ``` {/* SCHEMA_SYNC_END: admin/config/site.schema.json */} + #### Known bugs The following site configuration options require the server to be restarted for the changes to take effect: @@ -96268,7 +96532,6 @@ permissions.syncUsersMaxConcurrency If you are having trouble accessing the web UI, you can make edits to your site configuration by editing the configuration directly. - ### Sourcegraph with Docker Compose and single-server Sourcegraph with Docker Set `FRONTEND_CONTAINER` to: @@ -96377,7 +96640,7 @@ Settings options and their default values are shown below. {/* SCHEMA_SYNC_START: admin/config/settings.schema.json */} {/* WARNING: This section is auto-generated during releases. Do not edit manually. */} -{/* Last updated: 2025-07-28T21:25:29Z via sourcegraph/sourcegraph@v6.6.868 */} +{/* Last updated: 2025-08-07T02:20:39Z via sourcegraph/sourcegraph@v6.6.2517 */} ```json { @@ -96618,20 +96881,22 @@ Add the proxy environment variables to your Sourcegraph Helm chart [override fil ```yaml executor|frontend|gitserver|migrator|worker: env: - - name: HTTP_PROXY - value: http://proxy.example.com:8080 - - name: HTTPS_PROXY - value: http://proxy.example.com:8080 - - name: NO_PROXY - value: "blobstore,codeinsights-db,codeintel-db,sourcegraph-frontend-internal,sourcegraph-frontend,github-proxy,gitserver,grafana,indexed-search-indexer,indexed-search,jaeger-query,pgsql,precise-code-intel-worker,prometheus,redis-cache,redis-store,searcher,syntect-server,worker-executors,worker,cloud-sql-proxy,localhost,127.0.0.1,.svc,.svc.cluster.local,kubernetes.default.svc" + HTTP_PROXY: + value: http://proxy.example.com:8080 + HTTPS_PROXY: + value: http://proxy.example.com:8080 + NO_PROXY: + value: "blobstore,codeinsights-db,codeintel-db,sourcegraph-frontend-internal,sourcegraph-frontend,gitserver,grafana,indexed-search-indexer,indexed-search,jaeger-query,pgsql,precise-code-intel-worker,prometheus,redis-cache,redis-store,searcher,syntect-server,worker-executors,worker,cloud-sql-proxy,localhost,127.0.0.1,.svc,.svc.cluster.local,kubernetes.default.svc" ``` -If the updated Sourcegraph pods fail to pass their readiness or health checks after configuring the HTTP proxy environment variables, you may also need to add your k8s cluster pod & service CIDR ranges to the `NO_PROXY` environment variable. Example: +If the updated Sourcegraph pods fail to pass their readiness or health checks after configuring the HTTP proxy environment variables, you may also need to add your k8s cluster pod & service CIDR ranges to the `NO_PROXY` environment variable. For example, if the k8s cluster pod & service CIDR ranges are `10.10.0.0/16` and `10.20.0.0/16`, configure the `NO_PROXY` environment variable as: ```yaml -- name: NO_PROXY - value: "blobstore,codeinsights-db,codeintel-db,sourcegraph-frontend-internal,sourcegraph-frontend,github-proxy,gitserver,grafana,indexed-search-indexer,indexed-search,jaeger-query,pgsql,precise-code-intel-worker,prometheus,redis-cache,redis-store,searcher,syntect-server,worker-executors,worker,cloud-sql-proxy,localhost,127.0.0.1,.svc,.svc.cluster.local,kubernetes.default.svc,10.10.0.0/16,10.20.0.0/16" +executor|frontend|gitserver|migrator|worker: + env: + NO_PROXY: + value: "blobstore,codeinsights-db,codeintel-db,sourcegraph-frontend-internal,sourcegraph-frontend,gitserver,grafana,indexed-search-indexer,indexed-search,jaeger-query,pgsql,precise-code-intel-worker,prometheus,redis-cache,redis-store,searcher,syntect-server,worker-executors,worker,cloud-sql-proxy,localhost,127.0.0.1,.svc,.svc.cluster.local,kubernetes.default.svc,10.10.0.0/16,10.20.0.0/16" ``` @@ -96928,12 +97193,14 @@ See this [stackexchange](https://dba.stackexchange.com/questions/275378/dev-shm- -# Outoing Connection Filtering +# Outgoing Connection Filtering + Sourcegraph supports outbound connection filtering. Both for regular external connections and so-called "untrusted" connections, where a regular user can provide a URL to make an outbound connection to. The allow- and denylist support a comma separated list of IP ranges, hostnames and keywords. To block or allow all the internal connections use the “private” keyword, this would block all RFC 1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) and RFC 4193 (FC00::/7) IP addresses. Keywords can be combined with ranges and IP addresses so it's very customizable. ## Trusted External Connections + It’s possible for the Sourcegraph instance to deny access to external hosts by setting the environment variable `EXTERNAL_DENY_LIST` on the deployment. The default denylist is set up to only block localhost and the Cloud metadata service IP address. Expanding the denylist could interfere with internal authentication providers, and they might need to be excluded from the denylist. @@ -96949,9 +97216,11 @@ EXTERNAL_DENY_LIST="private,github.com" This would deny all connections to hosts in the private network and github.com. ## Untrusted External Connections + Codemonitors, webhooks and Cody URL context are limited to only be able to access public IP addresses by default. This behavior can be changed with the `UNTRUSTED_EXTERNAL_ALLOW_LIST` environment variable, which configures the allowlist. ### Example Configuration + If you want Cody to use context from an internal server in addition to internet access, you can add the internal server's IP address to the allowlist: ``` @@ -96959,6 +97228,7 @@ UNTRUSTED_EXTERNAL_ALLOW_LIST="external,192.168.1.53" ``` ## Implementation Details + To achieve this, we use [gitea's hostmatcher](https://github.com/go-gitea/gitea/blob/v1.22.6/modules/hostmatcher/hostmatcher.go#L39). This is configured by default for the `ExternalClient`, which is used for all external requests. The common options and configuration can be found [here](https://github.com/sourcegraph/sourcegraph-public-snapshot/blob/main/internal/httpcli/client.go#L406C1-L423C2). @@ -97077,7 +97347,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). +Sourcegraph Cloud customers can take advantage of mananged SMTP servers - [learn more](/cloud/#managed-smtp). ## User email verification @@ -97095,7 +97365,7 @@ To verify their email address, the user can do one of the following: Users with emails [created by the site admin](/admin/auth/#creating-builtin-authentication-users) through the `/site-admin/users/new` UI will have the same behaviour as the above. Users created directly through GraphQL or the `src` CLI assume that the email provided is verified. -> Note: For SSO (Single Sign-On) enabled instances, it is important to remove the basic authentication method from the `auth.providers` list to prevent users from receiving password reset links. This is because users do not need passwords to log in to SSO-enabled instances. Prior to disabling the basic authentication method, please ensure that there is at least one administrator account capable of signing in via SSO. This is essential because once basic authentication is disabled, the username/password combination used to create the initial admin account will no longer be functional. +For SSO (Single Sign-On) enabled instances, it is important to remove the basic authentication method from the `auth.providers` list to prevent users from receiving password reset links. This is because users do not need passwords to log in to SSO-enabled instances. Prior to disabling the basic authentication method, please ensure that there is at least one administrator account capable of signing in via SSO. This is essential because once basic authentication is disabled, the username/password combination used to create the initial admin account will no longer be functional. ## Configuring Sourcegraph to send email via Amazon AWS / SES @@ -97263,14 +97533,10 @@ Batch Changes is generally configured through the same [site configuration](/adm ## Access control - Feature supported only in Sourcegraph versions 5.0 or more. - Batch Changes is [RBAC-enabled](/admin/access_control/) Beta. By default, all users have full read and write access for Batch Changes, but this can be restricted by changing the default role permissions, or by creating new custom roles. ### Enable organization members to administer - Feature supported only in Sourcegraph versions 5.0.5 or more. - By default, only a batch change's author or a site admin can administer (apply, close, rename, etc.) a batch change. However, admins can use [organizations](/admin/organizations) to facilitate closer collaboration and shared administrative control over batch changes by enabling the `orgs.allMembersBatchChangesAdmin` setting for an organization. When enabled, members of the organization will be able to administer all batch changes created in that organization's namespace. Batch changes created in other namespaces (user or organization) will still be restricted to the author and site admins. ## Rollout windows @@ -97392,14 +97658,10 @@ To only allow changesets to be reconciled at 1 changeset per minute on (UTC) wee ## Incoming webhooks - Feature supported only in Sourcegraph versions 3.33 or more. - Sourcegraph can track incoming webhooks from code hosts to more easily debug issues with webhook delivery. Learn [how to setup webhooks and configure logging](/admin/config/webhooks/incoming#webhook-logging). ## Forks - Feature supported only in Sourcegraph versions 3.36 or more. - Sourcegraph can be configured to push branches created by Batch Changes to a fork of the repository, rather than the repository itself, for example if users of your code host typically do not have push access to the original repository. You can enable pushing to forks globally with the `batchChanges.enforceForks` site configuration option. Users can also indicate they do or do not want to push to forks for an individual batch change by specifying the property `changesetTemplate.fork` in their batch spec. If the batch spec property is present, it will override the site configuration option. See the [batch spec YAML reference](/batch-changes/batch-spec-yaml-reference#changesettemplatefork) for more information. The fork will be created in the namespace of the user publishing the changeset, or the namespace of the service account if [global service account](/batch-changes/configuring-credentials#global-service-account-tokens) is in use. The name of the fork Sourcegraph creates will be prefixed with the name of the original repo's namespace in order to prevent potential repo name collisions. For example, a batch spec targeting `github.com/my-org/project` would create or use any existing fork by the name `github.com/user/my-org-project`. @@ -97416,8 +97678,6 @@ To enable forks, update the site configuration to include: ## Automatically delete branches on merge/close - Feature supported only in Sourcegraph versions 5.1 or more. - Sourcegraph can be configured to automatically delete branches created for Batch Changes changesets when changesets are merged or closed by enabling the `batchChanges.autoDeleteBranch` site configuration option. When enabled, Batch Changes will override any setting on the repository on the code host itself and attempt to remove the source branch of the changeset when the changeset is merged or closed. This is useful for keeping repositories clean of stale branches. @@ -97564,8 +97824,6 @@ Installation access tokens are short-lived, non-refreshable tokens that give Sou ### Rejecting Unverified Commits - Feature supported only in Sourcegraph versions 5.2.4 or more. - Admins can configure Batch Changes to error when it creates commits that are not signed. This can be done by enabling the `batchChanges.rejectUnverifiedCommits` setting in the site configuration: ```json @@ -98958,7 +99216,7 @@ The Sourcegraph instance's site admin must [update the `corsOrigin` site config {/* SCHEMA_SYNC_START: admin/code_hosts/phabricator.schema.json */} {/* WARNING: This section is auto-generated during releases. Do not edit manually. */} -{/* Last updated: 2025-07-28T21:25:38Z via sourcegraph/sourcegraph@v6.6.868 */} +{/* Last updated: 2025-08-07T02:20:47Z via sourcegraph/sourcegraph@v6.6.2517 */} ```json { // SSH cipher to use when cloning via SSH. Must be a valid choice from `ssh -Q cipher`. @@ -99060,7 +99318,7 @@ Repositories must be listed individually: {/* SCHEMA_SYNC_START: admin/code_hosts/other_external_service.schema.json */} {/* WARNING: This section is auto-generated during releases. Do not edit manually. */} -{/* Last updated: 2025-07-28T21:25:39Z via sourcegraph/sourcegraph@v6.6.868 */} +{/* Last updated: 2025-08-07T02:20:48Z via sourcegraph/sourcegraph@v6.6.2517 */} ```json { // A list of repositories to never mirror by name after applying repositoryPathPattern. Supports excluding by exact name ({"name": "myrepo"}) or regular expression ({"pattern": ".*secret.*"}). @@ -99238,14 +99496,12 @@ See [an example YAML file containing available configuration options](https://gi # Code host connections - [Enterprise Starter](/pricing/enterprise-starter) only supports GitHub. [Enterprise](/pricing/enterprise) supports all listed code hosts. + [Enterprise Starter](/pricing/enterprise-starter) only supports GitHub.com, GitLab.com, and Bitbucket.org. [Enterprise](/pricing/enterprise) supports all listed code hosts. Available via the Web app. -Sourcegraph Enterprise Starter supports only GitHub as a code host connection. Enterprise plan can connect to all supported code hosts listed on this page. - Sourcegraph can sync repositories from code hosts and other similar services. We designate code hosts between Tier 1 and Tier 2 based on Sourcegraph's capabilities when used with those code hosts. ## Tier 1 code hosts @@ -99328,12 +99584,6 @@ To use Sourcegraph with self-signed TLS Certificates, update the site configurat } ``` -## Testing Code Host Connections - -> WARNING: Sourcegraph 4.4.0 customers are reporting a bug where the connection test is failing when Sourcegraph is running behind proxies where TCP dial cannot be used with ports 80/443. This causes repositories to stop syncing. If you're experiencing this issue, please upgrade to 4.4.1 where normal HTTP requests are used instead. - -In Sourcegraph 4.4, site administrators have the ability to test a code host connection via the site-admin UI to improve the debuggability when something goes wrong. This check confirms that Sourcegraph has the ability to connect with the respective code host via TCP dial. - @@ -99366,7 +99616,7 @@ To connect Gitolite to Sourcegraph: {/* SCHEMA_SYNC_START: admin/code_hosts/gitolite.schema.json */} {/* WARNING: This section is auto-generated during releases. Do not edit manually. */} -{/* Last updated: 2025-07-28T21:25:37Z via sourcegraph/sourcegraph@v6.6.868 */} +{/* Last updated: 2025-08-07T02:20:46Z via sourcegraph/sourcegraph@v6.6.2517 */} ```json { // A list of repositories to never mirror from this Gitolite instance. Supports excluding by exact name ({"name": "foo"}). @@ -99607,7 +99857,7 @@ See [Internal rate limits](/admin/code_hosts/rate_limits#internal-rate-limits). {/* SCHEMA_SYNC_START: admin/code_hosts/gitlab.schema.json */} {/* WARNING: This section is auto-generated during releases. Do not edit manually. */} -{/* Last updated: 2025-07-28T21:25:31Z via sourcegraph/sourcegraph@v6.6.868 */} +{/* Last updated: 2025-08-07T02:20:41Z via sourcegraph/sourcegraph@v6.6.2517 */} ```json { // If non-null, enforces GitLab repository permissions. This requires that there be an item in the `auth.providers` field of type "gitlab" with the same `url` field as specified in this `GitLabConnection`. @@ -99951,6 +100201,16 @@ To use a GitHub Enterprise App with Sourcegraph: 1. Create the Enterprise App in your GitHub Enterprise settings (see [GitHub's documentation](https://docs.github.com/en/enterprise-cloud@latest/admin/managing-your-enterprise-account/creating-github-apps-for-your-enterprise)) 2. Use the [**Add an existing GitHub App**](#adding-an-existing-github-app) option in Sourcegraph to connect it +If you get an error message similar to following error while adding a GitHub App connection : + +``` +"request to https://api.github.com/app/installations?page=1 returned status 403: Although you appear to have the correct authorization credentials, the `testsourcegraph` organization has an IP allow list enabled, and your IP address is not permitted to access this resource." + +``` + + It means that the IP allowlist is enabled at the organisation level and you will need to add sourcegraph's IP addresseses to this allowlist in order for the app connection to work (see [GitHub's documentation](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#adding-an-allowed-ip-address)) + + ### Uninstalling an App You can uninstall a GitHub App from a namespace or remove it altogether at any time. @@ -100234,7 +100494,7 @@ GitHub connections support the following configuration options, which are specif {/* SCHEMA_SYNC_START: admin/code_hosts/github.schema.json */} {/* WARNING: This section is auto-generated during releases. Do not edit manually. */} -{/* Last updated: 2025-07-28T21:25:30Z via sourcegraph/sourcegraph@v6.6.868 */} +{/* Last updated: 2025-08-07T02:20:40Z via sourcegraph/sourcegraph@v6.6.2517 */} ```json // Authentication alternatives: token OR gitHubAppDetails OR externalAccount OR useRandomExternalAccount @@ -100517,7 +100777,7 @@ Gerrit connections support the following configuration options, which are specif {/* SCHEMA_SYNC_START: admin/code_hosts/gerrit.schema.json */} {/* WARNING: This section is auto-generated during releases. Do not edit manually. */} -{/* Last updated: 2025-07-28T21:25:36Z via sourcegraph/sourcegraph@v6.6.868 */} +{/* Last updated: 2025-08-07T02:20:45Z via sourcegraph/sourcegraph@v6.6.2517 */} ```json { // If non-null, enforces Gerrit repository permissions. This requires that there is an item in the [site configuration json](https://sourcegraph.com/docs/admin/config/site_config#auth-providers) `auth.providers` field, of type "gerrit" with the same `url` field as specified in this `GerritConnection`. @@ -100806,7 +101066,7 @@ Bitbucket Server / Bitbucket Data Center connections support the following confi {/* SCHEMA_SYNC_START: admin/code_hosts/bitbucket_server.schema.json */} {/* WARNING: This section is auto-generated during releases. Do not edit manually. */} -{/* Last updated: 2025-07-28T21:25:32Z via sourcegraph/sourcegraph@v6.6.868 */} +{/* Last updated: 2025-08-07T02:20:42Z via sourcegraph/sourcegraph@v6.6.2517 */} ```json // Authentication alternatives: token OR password @@ -101074,7 +101334,7 @@ Bitbucket Cloud connections support the following configuration options, which a {/* SCHEMA_SYNC_START: admin/code_hosts/bitbucket_cloud.schema.json */} {/* WARNING: This section is auto-generated during releases. Do not edit manually. */} -{/* Last updated: 2025-07-28T21:25:33Z via sourcegraph/sourcegraph@v6.6.868 */} +{/* Last updated: 2025-08-07T02:20:43Z via sourcegraph/sourcegraph@v6.6.2517 */} ```json { // The workspace access token to use when authenticating with Bitbucket Cloud. @@ -101263,7 +101523,7 @@ Azure DevOps connections support the following configuration options, which are {/* SCHEMA_SYNC_START: admin/code_hosts/azuredevops.schema.json */} {/* WARNING: This section is auto-generated during releases. Do not edit manually. */} -{/* Last updated: 2025-07-28T21:25:34Z via sourcegraph/sourcegraph@v6.6.868 */} +{/* Last updated: 2025-08-07T02:20:44Z via sourcegraph/sourcegraph@v6.6.2517 */} ```json // Authentication alternatives: token OR windowsPassword @@ -101430,7 +101690,7 @@ AWS CodeCommit connections support the following configuration options, which ar {/* SCHEMA_SYNC_START: admin/code_hosts/aws_codecommit.schema.json */} {/* WARNING: This section is auto-generated during releases. Do not edit manually. */} -{/* Last updated: 2025-07-28T21:25:35Z via sourcegraph/sourcegraph@v6.6.868 */} +{/* Last updated: 2025-08-07T02:20:45Z via sourcegraph/sourcegraph@v6.6.2517 */} ```json { // REQUIRED: @@ -101869,7 +102129,7 @@ The authentication providers are configured in the [`auth.providers`](/admin/con ## Programmatic authentication -For automated systems, CI/CD pipelines, and API integrations that need to authenticate without human interaction, use [service accounts](/admin/access_control/service_accounts). Service accounts are specialized user accounts designed for automation that authenticate using access tokens rather than passwords. +For automated systems, CI/CD pipelines, and API integrations that need to authenticate without human interaction, use [service accounts](/admin/service_accounts). Service accounts are specialized user accounts designed for automation that authenticate using access tokens rather than passwords. ## Login form configuration @@ -103140,69 +103400,6 @@ Ensure the following values are set for the application configuration in the ide - -# Service Accounts - -Service accounts are specialized user accounts designed for automation, API integrations, and programmatic access to Sourcegraph, as opposed to using access tokens from regular users. Unlike regular user accounts, service accounts don't require an email address or password, cannot access the Sourcegraph UI, don't count towards a license's user limit and won't be part of any billing cycles. - -## Creating Service Accounts - -Service accounts are created like regular user accounts, but with a few key differences. - -- Go to **Site admin** → **Users & auth** → **Users** -- Click **Create User** -- Enter a descriptive **Username** (e.g., `ci-bot-scip-uploads`, `api-search-jobs`) -- Check the **Service account** checkbox -- Click **Create service account** - -![create-service-account](https://storage.googleapis.com/sourcegraph-assets/Docs/create-service-accounts-0625.png) - -You'll be presented with some next steps you might want to take, like creating an access token, managing and assigning roles, and managing repository permissions. - -- Service accounts are automatically assigned the "Service Account" system role -- They appear in the user list with "Service account" type designation -- By default, service accounts can only access public and unrestricted repositories - -![next-steps-service-account](https://storage.googleapis.com/sourcegraph-assets/Docs/service-accounts-next-steps-0625.png) - -## Managing Access Tokens - -Service accounts authenticate using access tokens rather than passwords. For detailed information about creating, managing, and using access tokens, see: - -- [Creating an access token](/cli/how-tos/creating_an_access_token) -- [Managing access tokens](/cli/how-tos/managing_access_tokens) -- [Revoking an access token](/cli/how-tos/revoking_an_access_token) - -Use service account access tokens to access Sourcegraph's [GraphQL API](/api/graphql). - -## Role-Based Access Control (RBAC) - -Service accounts integrate with Sourcegraph's [role-based access control](/admin/access_control) to provide fine-grained permission control. - -### System Roles - -Service accounts are automatically assigned the **Service Account** system role, which provides basic API access permissions and standard search capabilities. The **Service Account** system role is applied to all service accounts and can be used to provide service accounts with a default set of permissions. For more specialized service accounts, it is recommended to create custom roles and assign them to service accounts as needed. - -### Managing Roles - -Administrators can assign additional roles to service accounts through the user management interface. For detailed information on managing roles and permissions, see: - -- [Managing roles and permissions](/admin/access_control#managing-roles-and-permissions) -- [Managing user roles](/admin/access_control#managing-user-roles) -- [Creating custom roles](/admin/access_control#creating-a-new-role-and-assigning-it-permissions) - -![service-account-roles](https://storage.googleapis.com/sourcegraph-assets/Docs/service-accounts-manage-roles-0625.png) - -## Repository Permissions - -Service accounts respect repository permissions and access controls. For comprehensive information about repository permissions, see the [Repository permissions](/admin/permissions) documentation. - -Service accounts by default can only access public and unrestricted repositories in Sourcegraph. You may explicitly grant fine-grained access to private repositories from the service account's user settings page, under the **Repo permissions** tab, or via [the GraphQL API](/admin/permissions/api#explicit-permissions-api). In the **Repo permissions** tab, you can also grant service accounts access to all current and future repositories on Sourcegraph, regardless of their visibility, which is useful for service accounts that need to do things like perform search jobs, but admins should take care to ensure that the access tokens for these accounts are not shared with unauthorized users. - -![service-account-repo-permissions](https://storage.googleapis.com/sourcegraph-assets/Docs/service-accounts-repo-permissions-0625.png) - - - # Access control for Ownership @@ -103226,9 +103423,7 @@ Name | Description | Granted to **User** by default? This feature is in Beta stage. -> NOTE: This page refers to in-product permissions, which determine who can, for example, create a batch change, or who is a site admin. This is *not* the same as [repository permissions](/admin/permissions/), which enforces the same repository access on Sourcegraph as your code host. - -> NOTE: Feature supported on Sourcegraph versions 5.0+ +This page refers to in-product permissions, which determine who can, for example, create a batch change, or who is a site admin. This is *not* the same as [repository permissions](/admin/permissions/), which enforces the same repository access on Sourcegraph as your code host. Sourcegraph uses [Role-Based Access Control (RBAC)](https://en.wikipedia.org/wiki/Role-based_access_control) to enable fine-grained control over different features and abilities of Sourcegraph, without having to modify permissions for each user individually. Currently, the scope of permissions control is limited to [Batch Changes](/admin/access_control/batch_changes) functionality, but it will be expanded to other areas in the future. @@ -103259,17 +103454,17 @@ You can read about the specific permission types available for each RBAC-enabled - [Batch Changes](/admin/access_control/batch_changes) - [Ownership](/admin/access_control/ownership) -- [Service accounts](/admin/access_control/service_accounts) +- [Service accounts](/admin/service_accounts) ### Deleting a role -> NOTE: Built-in system roles cannot be deleted. +Built-in system roles cannot be deleted. To delete a role, click the **Delete** button on it. You will be prompted to confirm your choice. Once deleted, all users previously assigned that role will lose all permissions associated with it. Be aware, though, that the same permissions could still be granted by their other roles. ## Managing user roles -> NOTE: Built-in system roles cannot be assigned this way. +Built-in system roles cannot be assigned this way. Site admins can manage which roles are assigned to which users from **Site admin > Users & auth > Users**. To view or edit a user's roles, click the triple dots to open the context menu for that user, then click **Manage roles**. This will open a modal dialog where you can see the user's current roles, assign new ones, or unassign current ones. You can type in the input field to search roles by name. Click **Update** to save any changes, or **Cancel** to discard. Note that system roles cannot be revoked or assigned via this modal. From 6ebda311de41751878b41def3ce8f730ede37fb9 Mon Sep 17 00:00:00 2001 From: Erik Seliger Date: Fri, 15 Aug 2025 17:56:10 +0200 Subject: [PATCH 4/6] Update docs/admin/oauth_apps.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: ᴊᴏᴇ ᴄʜᴇɴ --- docs/admin/oauth_apps.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/oauth_apps.mdx b/docs/admin/oauth_apps.mdx index 3c2031abf..85e12839a 100644 --- a/docs/admin/oauth_apps.mdx +++ b/docs/admin/oauth_apps.mdx @@ -1,6 +1,6 @@ # OAuth Apps -OAuth Apps let you build rich third-party experiences that call Sourcegraph **on behalf of end-users while honoring their repository permissions**. Every API request made with an OAuth access token is evaluated against the same authorization rules that apply inside the Sourcegraph UI, so your integration only sees the code each user is allowed to see. +OAuth Apps let you build rich third-party experiences that interact with Sourcegraph **on behalf of end-users while honoring their repository permissions**. Every API request made with an OAuth access token is evaluated against the same authorization rules that apply inside the Sourcegraph UI, so your integration only sees the code each user is allowed to see. This makes OAuth the preferred choice for any multi-user integration like browser extensions, IDE plugins, chatbots, internal tools, or SaaS platforms where you need to: From 94e2af4703d29e75663b6f0f89e3902393e5f404 Mon Sep 17 00:00:00 2001 From: Erik Seliger Date: Fri, 15 Aug 2025 17:56:17 +0200 Subject: [PATCH 5/6] Update docs/admin/oauth_apps.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: ᴊᴏᴇ ᴄʜᴇɴ --- docs/admin/oauth_apps.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/oauth_apps.mdx b/docs/admin/oauth_apps.mdx index 85e12839a..9e397803d 100644 --- a/docs/admin/oauth_apps.mdx +++ b/docs/admin/oauth_apps.mdx @@ -9,7 +9,7 @@ This makes OAuth the preferred choice for any multi-user integration like browse - Rely on short-lived, scoped tokens that can be revoked at any time - Guarantee that repository visibility and other access controls are enforced automatically -OAuth Apps follow standards [RFC 6749](https://tools.ietf.org/html/rfc6749), [RFC 7636 (PKCE)](https://tools.ietf.org/html/rfc7636), and [RFC 8628 (Device Authorization Grant)](https://tools.ietf.org/html/rfc8628). +OAuth Apps are in compliance with standards including [RFC 6749](https://tools.ietf.org/html/rfc6749), [RFC 7636 (PKCE)](https://tools.ietf.org/html/rfc7636), and [RFC 8628 (Device Authorization Grant)](https://tools.ietf.org/html/rfc8628). Consider using **M2M (client-credentials) service-account tokens** or traditional [access tokens](/admin/access_control/access_tokens) for server-to-server communication, automated scripts, CI/CD pipelines, or single-user applications that do not require per-user permission checks. See [service accounts](/admin/service_accounts#m2m-oauth-credentials-client-credentials-flow) for details. From f3c2c12165979f3d611f4a790d23662d055cf79d Mon Sep 17 00:00:00 2001 From: Erik Seliger Date: Fri, 15 Aug 2025 18:10:47 +0200 Subject: [PATCH 6/6] Update docs/admin/oauth_apps.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: ᴊᴏᴇ ᴄʜᴇɴ --- docs/admin/oauth_apps.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/oauth_apps.mdx b/docs/admin/oauth_apps.mdx index 9e397803d..71a54e9e1 100644 --- a/docs/admin/oauth_apps.mdx +++ b/docs/admin/oauth_apps.mdx @@ -327,7 +327,7 @@ curl -X POST https://sourcegraph.example.com/.auth/idp/oauth/token \ -d "client_secret=YOUR_CLIENT_SECRET" # Only for private clients ``` -**Important**: Always store the new refresh token returned in the response, as it may differ from the one you used in the request. +**Important**: Always store the new refresh token returned in the response, as it may differ from the one you used in the request. Every refresh token is strictly one-time use, your application needs to handle the case when it's possible to have multiple processes initiating the token refresh process because only one of them will succeed for the same refresh token. ### Token Expiration Handling