Skip to main content
Site configuration controls how Sourcegraph behaves for all users. It is a JSON document edited at Site admin > Configuration (/site-admin/configuration). Changes take effect immediately unless noted otherwise.
Some settings require a frontend service restart to take effect: auth.providers, externalURL, insights.query.worker.concurrency, and permissions.syncUsersMaxConcurrency.

​
Essential settings

Every Sourcegraph instance should configure at minimum: 
{
  "externalURL": "https://sourcegraph.example.com",
  "auth.providers": [
    {
      "type": "builtin",
      "allowSignup": false
    }
  ],
  "licenseKey": "your-enterprise-license-key"
}
  • externalURL: The publicly accessible URL for your instance. Required for auth callbacks, email links, and webhooks to work correctly. Use the exact scheme (https://), no trailing slash.
  • auth.providers: Configures sign-in. See Authentication for all options.
  • licenseKey: Activates Enterprise features. Contact [email protected] for a key.

​
Code host connections

Code host connections are configured at Site admin > Manage code hosts, not directly in site config JSON. Each connection type uses a JSON configuration object specific to that host.

​
GitHub

{
  "url": "https://github.com",
  "token": "ghp_your_personal_access_token",
  "orgs": ["your-org"],
  "repos": ["your-org/specific-repo"],
  "repositoryQuery": ["affiliated"],
  "authorization": {
    "identityProvider": {
      "type": "oauth"
    }
  }
}
Key fields:
  • url: Use https://github.com for GitHub.com, or your GitHub Enterprise URL.
  • token: A personal access token or GitHub App with repo and read:org scopes.
  • orgs / repos: Control which repositories are synced.
  • authorization: Enable permission syncing so users only see repositories they have access to on GitHub.

​
GitLab

{
  "url": "https://gitlab.example.com",
  "token": "your-gitlab-personal-access-token",
  "projectQuery": ["groups/my-group/projects?membership=true"],
  "authorization": {
    "identityProvider": {
      "type": "oauth"
    }
  }
}
The token needs read_api scope. Add api scope if you are using Batch Changes.

​
Bitbucket Cloud

{
  "url": "https://bitbucket.org",
  "username": "your-username",
  "appPassword": "your-app-password",
  "teams": ["your-workspace"],
  "authorization": {}
}
Create a Bitbucket Cloud app password with Repositories: Read and Account: Read permissions.

​
Bitbucket Server / Data Center

{
  "url": "https://bitbucket.example.com",
  "token": "your-personal-access-token",
  "repositoryQuery": ["all"],
  "authorization": {
    "identityProvider": {
      "type": "username"
    }
  }
}

​
Gerrit

{
  "url": "https://gerrit.example.com",
  "username": "sourcegraph",
  "password": "http-password",
  "projects": ["your-project"]
}
After adding a code host connection, go to Site admin > Repositories to verify that repositories are being synced. Initial sync can take several minutes depending on the number of repositories.

​
Repository permissions

Sourcegraph can enforce the same repository access controls your code host uses. When permissions are enabled, users only see repositories they can access on the code host. Enable permissions syncing by adding authorization to your code host configuration (shown in the examples above). Then tune the sync schedule: 
{
  "permissions.syncScheduleInterval": 60,
  "permissions.syncReposBackoffSeconds": 900,
  "permissions.syncUsersBackoffSeconds": 900,
  "permissions.syncReposMaxConcurrency": 5,
  "permissions.syncUsersMaxConcurrency": 5
}
Explicit permissions via API — if you manage permissions outside the code host, you can use the GraphQL API to set them directly: 
{
  "permissions.userMapping": {
    "enabled": true,
    "bindID": "email"
  }
}
Set bindID to "email" (default) or "username" to control how Sourcegraph matches API-supplied permissions to user accounts.
If you enable authz.enforceForSiteAdmins, site admins will only see repositories they have access to via the permissions system, rather than all repositories.

​
Search settings

{
  "search.limits": {
    "maxRepos": -1,
    "maxTimeoutSeconds": 60,
    "commitDiffMaxRepos": 50,
    "commitDiffWithTimeFilterMaxRepos": 10000
  },
  "search.largeFiles": ["go.sum", "package-lock.json"],
  "search.index.symbols.enabled": false
}
  • search.limits.maxRepos: Maximum number of repositories searched in a single query. -1 means unlimited.
  • search.limits.maxTimeoutSeconds: Maximum search timeout. Increase for large instances where searches regularly time out.
  • search.largeFiles: Glob patterns for files that should be indexed regardless of size (must be valid UTF-8).
  • search.index.symbols.enabled: Enable symbol search in the index. Requires all repositories to re-index (time-consuming) and additional storage.

​
Email / SMTP

Configure SMTP to send password reset emails, access request notifications, and Code Monitor alerts. 
{
  "email.address": "[email protected]",
  "email.senderName": "Sourcegraph",
  "email.smtp": {
    "host": "smtp.example.com",
    "port": 587,
    "username": "smtp-user",
    "password": "smtp-password",
    "authentication": "PLAIN"
  }
}
authentication accepts "PLAIN", "CRAM-MD5", or "none". You can customize the subjects and bodies of password reset and account setup emails: 
{
  "email.templates": {
    "resetPassword": {
      "subject": "Reset your password on {{.Host}}",
      "body": "To reset your password, click: {{.URL}}"
    },
    "setPassword": {
      "subject": "Set your password on {{.Host}}",
      "body": "To set your password and complete registration, click: {{.URL}}\n\nYour username is: {{.Username}}"
    }
  }
}

​
Licensing

{
  "licenseKey": "your-enterprise-license-key"
}
The license key is validated on save. You can view your current license status and seat usage at Site admin > License. Instances without a license (or on the free tier) allow up to 10 users, and all users are created as site admins.

​
Batch Changes

{
  "batchChanges.enabled": true,
  "batchChanges.restrictToAdmins": false,
  "batchChanges.enforceForks": false,
  "batchChanges.autoDeleteBranch": false,
  "batchChanges.rolloutWindows": [
    {
      "days": ["saturday", "sunday"],
      "start": "06:00",
      "end": "20:00",
      "rate": "10/hour"
    }
  ]
}
  • batchChanges.restrictToAdmins: Limit batch change creation to site admins.
  • batchChanges.enforceForks: Push all batch changes branches to forks of the target repository.
  • batchChanges.rolloutWindows: Throttle changeset publishing to specific days and times (UTC).

​
Branding

You can customize the Sourcegraph logo and browser favicon shown to users: 
{
  "branding": {
    "brandName": "Acme Sourcegraph",
    "light": {
      "logo": "https://example.com/logo-light.png",
      "symbol": "https://example.com/search-icon-light.png"
    },
    "dark": {
      "logo": "https://example.com/logo-dark.png",
      "symbol": "https://example.com/search-icon-dark.png"
    },
    "favicon": "https://example.com/favicon.ico"
  }
}

​
Security and session settings

{
  "auth.sessionExpiry": "2160h",
  "auth.minPasswordLength": 12,
  "auth.accessTokens": {
    "allow": "all-users-create",
    "allowNoExpiration": false,
    "defaultExpirationDays": 90
  },
  "auth.allowedIpAddress": {
    "enabled": false,
    "userIpAddress": null
  }
}
  • auth.sessionExpiry: Sessions expire after this duration (default: 90 days). Requires restart.
  • auth.minPasswordLength: Minimum password length for builtin auth (default: 12).
  • auth.accessTokens.allow: "all-users-create" (default), "site-admin-create", or "none".
  • auth.allowedIpAddress: Restrict instance access to specific IP ranges.

​
Editing site config without the web UI

If you cannot access the web UI, you can edit the site config directly in the container. 
docker exec -it sourcegraph-frontend sh -c 'vi ~/site-config.json'
Changes are applied immediately on save, the same as through the UI.
The full reference with all fields and defaults is maintained in the Sourcegraph source. You can view it at Site admin > Configuration — the editor shows inline documentation for each field as you type.
Some settings require a frontend service restart: auth.providers, externalURL, insights.query.worker.concurrency, and permissions.syncUsersMaxConcurrency. Check the frontend container logs for errors if a change does not appear to apply.
Replace the contents with the minimal default config:
{
  "externalURL": "https://sourcegraph.example.com",
  "auth.providers": [
    {
      "type": "builtin",
      "allowSignup": false
    }
  ]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us