Site configuration

Site configuration defines how various Sourcegraph features behave. See the full reference below for a comprehensive list of site configuration options.

Configuration overview

Go here for an overview of configuring Sourcegraph.

View and edit site configuration

Site admins can view and edit site configuration on a Sourcegraph instance:

  1. Go to User menu > Site admin.
  2. Open the Configuration page. (The URL is https://sourcegraph.example.com/site-admin/configuration.)

Reference

All site configuration options and their default values are shown below.

admin/config/site.schema.json

{
	// Configuration for API rate limiting
	"api.ratelimit": null,

	// Limit factor for API docs search index size. A multiple of 250 million symbols. 1.0 indicates 250 million symbols (approx 12.5k repos) can be indexed. 2.0 indicates double that, and so on. See https://docs.sourcegraph.com/code_intelligence/apidocs
	"apidocs.search.index-size-limit-factor": 1,

	// When true, site admins will only be able to see private code they have access to via our authz system.
	"authz.enforceForSiteAdmins": false,

	// Customize Sourcegraph homepage logo and search icon.
	//
	// Only available in Sourcegraph Enterprise.
	"branding": null,
	// Other example values:
	// - {
	//     "dark": {
	//       "logo": "https://example.com/logo_dark.png",
	//       "symbol": "https://example.com/search_symbol_dark_24x24.png"
	//     },
	//     "disableSymbolSpin": true,
	//     "favicon": "https://example.com/favicon.ico",
	//     "light": {
	//       "logo": "https://example.com/logo_light.png",
	//       "symbol": "https://example.com/search_symbol_light_24x24.png"
	//     }
	//   }

	// Configuration for encryption keys used to encrypt data at rest in the database.
	"encryption.keys": null,

	// The shared secret between Sourcegraph and executors.
	"executors.accessToken": null,

	// Enable to allow users to add external services for public and private repositories to the Sourcegraph instance.
	"externalService.userMode": "disabled",

	// The externally accessible URL for Sourcegraph (i.e., what you type into your browser). Previously called `appURL`. Only root URLs are allowed.
	"externalURL": null,
	// Other example values:
	// - "https://sourcegraph.example.com"

	// Configure notifications for Sourcegraph's built-in alerts.
	"observability.alerts": null,

	// Silence individual Sourcegraph alerts by identifier.
	"observability.silenceAlerts": null,

	// Controls the settings for distributed tracing.
	"observability.tracing": null,

//////////////////////////////////////////////////////////////
// Authentication
//////////////////////////////////////////////////////////////

	// Enables users to change their username after account creation. Warning: setting this to be true has security implications if you have enabled (or will at any point in the future enable) repository permissions with an option that relies on username equivalency between Sourcegraph and an external service or authentication provider. Do NOT set this to true if you are using non-built-in authentication OR rely on username equivalency for repository permissions.
	"auth.enableUsernameChanges": false,

	// The minimum number of Unicode code points that a password must contain.
	"auth.minPasswordLength": 12,

	// The duration (in seconds) that a password reset link is considered valid.
	"auth.passwordResetLinkExpiry": 14400,

	// The authentication providers to use for identifying and signing in users. See instructions below for configuring SAML, OpenID Connect (including Google Workspace), and HTTP authentication proxies. Multiple authentication providers are supported (by specifying multiple elements in this array).
	"auth.providers": [
		{
			"allowSignup": true,
			"type": "builtin"
		}
	],

	// WARNING: This option has been removed as of 3.8.
	"auth.public": false,

	// The duration of a user session, after which it expires and the user is required to re-authenticate. The default is 90 days. There is typically no need to set this, but some users may have specific internal security requirements.
	//
	// The string format is that of the Duration type in the Go time package (https://golang.org/pkg/time/#ParseDuration). E.g., "720h", "43200m", "2592000s" all indicate a timespan of 30 days.
	//
	// Note: changing this field does not affect the expiration of existing sessions. If you would like to enforce this limit for existing sessions, you must log out currently signed-in users. You can force this by removing all keys beginning with "session_" from the Redis store:
	//
	// * For deployments using `sourcegraph/server`: `docker exec $CONTAINER_ID redis-cli --raw keys 'session_*' | xargs docker exec $CONTAINER_ID redis-cli del`
	// * For cluster deployments: 
	//   ```
	//   REDIS_POD="$(kubectl get pods -l app=redis-store -o jsonpath={.items[0].metadata.name})";
	//   kubectl exec "$REDIS_POD" -- redis-cli --raw keys 'session_*' | xargs kubectl exec "$REDIS_POD" -- redis-cli --raw del;
	//   ```
	"auth.sessionExpiry": "2160h",
	// Other example values:
	// - "168h"

//////////////////////////////////////////////////////////////
// BatchChanges
//////////////////////////////////////////////////////////////

	// Enables/disables the Batch Changes feature.
	"batchChanges.enabled": true,

	// When enabled, only site admins can create and apply batch changes.
	"batchChanges.restrictToAdmins": false,

	// Specifies specific windows, which can have associated rate limits, to be used when publishing changesets. All days and times are handled in UTC.
	"batchChanges.rolloutWindows": null,

//////////////////////////////////////////////////////////////
// Campaigns
//////////////////////////////////////////////////////////////

	// DEPRECATED: Use batchChanges.enabled instead. Enables/disables the campaigns feature.
	"campaigns.enabled": true,

	// DEPRECATED: Use batchChanges.restrictToAdmins instead. When enabled, only site admins can create and apply campaigns.
	"campaigns.restrictToAdmins": false,

//////////////////////////////////////////////////////////////
// Code intelligence
//////////////////////////////////////////////////////////////

	// Enables/disables the code intel auto indexing feature. This feature is currently supported only on certain managed Sourcegraph instances.
	"codeIntelAutoIndexing.enabled": false,

//////////////////////////////////////////////////////////////
// CodeInsights
//////////////////////////////////////////////////////////////

	// The interval (in minutes) at which the insights commit indexer will check for new commits.
	"insights.commit.indexer.interval": 60,
	// Other example values:
	// - 120

	// Maximum number of historical Code Insights data frames that may be analyzed per second.
	"insights.historical.worker.rateLimit": 10,
	// Other example values:
	// - 50
	// - 0.5

	// Number of concurrent executions of a code insight query on a worker node
	"insights.query.worker.concurrency": 1,
	// Other example values:
	// - 10

	// Maximum number of Code Insights queries initiated per second on a worker node.
	"insights.query.worker.rateLimit": 2,
	// Other example values:
	// - 10
	// - 0.5

//////////////////////////////////////////////////////////////
// Debug
//////////////////////////////////////////////////////////////

	// (debug) controls the amount of symbol search parallelism. Defaults to 20. It is not recommended to change this outside of debugging scenarios. This option will be removed in a future version.
	"debug.search.symbolsParallelism": null,
	// Other example values:
	// - ["20"]

	// (debug) duration of historical insights timeframes, one point per repository will be recorded in each timeframe.
	"insights.historical.frameLength": null,
	// Other example values:
	// - "30d"

	// (debug) number of historical insights timeframes to populate
	"insights.historical.frames": null,
	// Other example values:
	// - ["6"]

	// (debug) Speed factor for building historical insights data. A value like 1.5 indicates approximately to use 1.5x as much repo-updater and gitserver resources.
	"insights.historical.speedFactor": null,
	// Other example values:
	// - "1.0"

	// (debug) logs all GraphQL requests slower than the specified number of milliseconds.
	"observability.logSlowGraphQLRequests": null,
	// Other example values:
	// - ["10000"]

	// (debug) logs all search queries (issued by users, code intelligence, or API requests) slower than the specified number of milliseconds.
	"observability.logSlowSearches": null,
	// Other example values:
	// - ["10000"]

//////////////////////////////////////////////////////////////
// Email
//////////////////////////////////////////////////////////////

	// The "from" address for emails sent by this server.
	"email.address": "[email protected]",

	// The SMTP server used to send transactional emails (such as email verifications, reset-password emails, and notifications).
	"email.smtp": null,
	// Other example values:
	// - {
	//     "authentication": "PLAIN",
	//     "host": "smtp.example.com",
	//     "password": "mypassword",
	//     "port": 465,
	//     "username": "alice"
	//   }

//////////////////////////////////////////////////////////////
// Experimental
//////////////////////////////////////////////////////////////

	// Experimental features to enable or disable. Features that are now enabled by default are marked as deprecated.
	"experimentalFeatures": null,
	// Other example values:
	// - {
	//     "customGitFetch": [
	//       {
	//         "domainPath": "somecodehost.com/path/to/repo",
	//         "fetch": "customgitbinary someflag"
	//       },
	//       {
	//         "domainPath": "somecodehost.com/path/to/anotherrepo",
	//         "fetch": "customgitbinary someflag anotherflag"
	//       }
	//     ]
	//   }

//////////////////////////////////////////////////////////////
// Extensions
//////////////////////////////////////////////////////////////

	// Configures Sourcegraph extensions.
	"extensions": {
		"remoteRegistry": "https://sourcegraph.com/.api/registry"
	},
	// Other example values:
	// - {
	//     "allowRemoteExtensions": [
	//       "sourcegraph/java"
	//     ],
	//     "remoteRegistry": "https://sourcegraph.com/.api/registry"
	//   }

//////////////////////////////////////////////////////////////
// External services
//////////////////////////////////////////////////////////////

	// Disable periodic syncs of configured code host connections (repository metadata, permissions, batch changes changesets, etc)
	"disableAutoCodeHostSyncs": false,

	// Disable periodically fetching git contents for existing repositories.
	"disableAutoGitUpdates": false,

	// Disable redirects to sourcegraph.com when visiting public repositories that can't exist on this server.
	"disablePublicRepoRedirects": null,

	// JSON array of configuration that maps from Git clone URL to repository name. Sourcegraph automatically resolves remote clone URLs to their proper code host. However, there may be non-remote clone URLs (e.g., in submodule declarations) that Sourcegraph cannot automatically map to a code host. In this case, use this field to specify the mapping. The mappings are tried in the order they are specified and take precedence over automatic mappings.
	"git.cloneURLToRepositoryName": null,

	// Maximum number of seconds that a long Git command (e.g. clone or remote update) is allowed to execute. The default is 3600 seconds, or 1 hour.
	"gitLongCommandTimeout": 3600,

	// Maximum number of remote code host git operations (e.g. clone or ls-remote) to be run per second per gitserver. Default is -1, which is unlimited.
	"gitMaxCodehostRequestsPerSecond": -1,

	// Maximum number of git clone processes that will be run concurrently per gitserver to update repositories. Note: the global git update scheduler respects gitMaxConcurrentClones. However, we allow each gitserver to run upto gitMaxConcurrentClones to allow for urgent fetches. Urgent fetches are used when a user is browsing a PR and we do not have the commit yet.
	"gitMaxConcurrentClones": 5,

	// JSON array of repo name patterns and update intervals. If a repo matches a pattern, the associated interval will be used. If it matches no patterns a default backoff heuristic will be used. Pattern matches are attempted in the order they are provided.
	"gitUpdateInterval": null,

	// URL to fetch unreachable repository details from. Defaults to "https://sourcegraph.com"
	"parentSourcegraph": null,

	// The number of concurrent external service syncers that can run.
	"repoConcurrentExternalServiceSyncers": 3,

	// Interval (in minutes) for checking code hosts (such as GitHub, Gitolite, etc.) for new repositories.
	"repoListUpdateInterval": 1,

//////////////////////////////////////////////////////////////
// Misc.
//////////////////////////////////////////////////////////////

	// Disable aggregated event counts from being sent to Sourcegraph.com via pings.
	"disableNonCriticalTelemetry": false,

	// HTML to inject at the bottom of the `<body>` element on each page, for analytics scripts
	"htmlBodyBottom": null,

	// HTML to inject at the top of the `<body>` element on each page, for analytics scripts
	"htmlBodyTop": null,

	// HTML to inject at the bottom of the `<head>` element on each page, for analytics scripts
	"htmlHeadBottom": null,

	// HTML to inject at the top of the `<head>` element on each page, for analytics scripts
	"htmlHeadTop": null,

	// Configuration for logging and alerting, including to external services.
	"log": null,
	// Other example values:
	// - {
	//     "sentry": {
	//       "dsn": "https://[email protected]/myproject"
	//     }
	//   }

	// Enables users access to the product research page in their settings.
	"productResearchPage.enabled": true,

	// The channel on which to automatically check for Sourcegraph updates.
	"update.channel": "release",
	// Other example values:
	// - "none"

	// DEPRECATED. Use `"observability.tracing": { "sampling": "all" }`, instead. Enables Jaeger tracing.
	"useJaeger": null,

	// The site wide maximum number of repos that can be added by non site admins
	"userRepos.maxPerSite": 200000,

	// The per user maximum number of repos that can be added by non site admins
	"userRepos.maxPerUser": 2000,

//////////////////////////////////////////////////////////////
// Search
//////////////////////////////////////////////////////////////

	// Whether built-in searches should be hidden on the Searches page.
	"disableBuiltInSearches": null,

	// Set to `true` to not include symbol results if no `type:` filter was given
	"dontIncludeSymbolResultsByDefault": null,

	// DEPRECATED: Configure maxRepos in search.limits. The maximum number of repositories to search across. The user is prompted to narrow their query if exceeded. Any value less than or equal to zero means unlimited.
	"maxReposToSearch": -1,

	// Whether indexed search is enabled. If unset Sourcegraph detects the environment to decide if indexed search is enabled. Indexed search is RAM heavy, and is disabled by default in the single docker image. All other environments will have it enabled by default. The size of all your repository working copies is the amount of additional RAM required.
	"search.index.enabled": null,

	// Whether indexed symbol search is enabled. This is contingent on the indexed search configuration, and is true by default for instances with indexed search enabled. Enabling this will cause every repository to re-index, which is a time consuming (several hours) operation. Additionally, it requires more storage and ram to accommodate the added symbols information in the search index.
	"search.index.symbols.enabled": null,

	// A list of file glob patterns where matching files will be indexed and searched regardless of their size. Files still need to be valid utf-8 to be indexed. The glob pattern syntax can be found here: https://golang.org/pkg/path/filepath/#Match.
	"search.largeFiles": null,
	// Other example values:
	// - [
	//     "go.sum",
	//     "package-lock.json",
	//     "*.thrift"
	//   ]

	// Limits that search applies for number of repositories searched and timeouts.
	"search.limits": null,

//////////////////////////////////////////////////////////////
// Security
//////////////////////////////////////////////////////////////

	// Settings for access tokens, which enable external tools to access the Sourcegraph API with the privileges of the user.
	"auth.accessTokens": {
		"allow": "all-users-create"
	},
	// Other example values:
	// - {"allow":"site-admin-create"}
	// - {"allow":"none"}

	// Required when using any of the native code host integrations for Phabricator, GitLab, or Bitbucket Server. It is a space-separated list of allowed origins for cross-origin HTTP requests which should be the base URL for your Phabricator, GitLab, or Bitbucket Server instance.
	"corsOrigin": null,
	// Other example values:
	// - "https://my-phabricator.example.com https://my-bitbucket.example.com https://my-gitlab.example.com"

	// Whether or not LSIF uploads will be blocked unless a valid LSIF upload token is provided.
	"lsifEnforceAuth": false,

	// Settings for Sourcegraph permissions, which allow the site admin to explicitly manage repository permissions via the GraphQL API. This setting cannot be enabled if repository permissions for any specific external service are enabled (i.e., when the external service's `authorization` field is set).
	"permissions.userMapping": {
		"bindID": "email",
		"enabled": true
	},
	// Other example values:
	// - {"bindID":"email"}
	// - {"bindID":"username"}

//////////////////////////////////////////////////////////////
// Sourcegraph Enterprise license
//////////////////////////////////////////////////////////////

	// The license key associated with a Sourcegraph product subscription, which is necessary to activate Sourcegraph Enterprise functionality. To obtain this value, contact Sourcegraph to purchase a subscription. To escape the value into a JSON string, you may want to use a tool like https://json-escape-text.now.sh.
	"licenseKey": null,

//////////////////////////////////////////////////////////////
// Sourcegraph.com
//////////////////////////////////////////////////////////////

	// Configuration options for Sourcegraph.com only.
	"dotcom": null
}

Known bugs

The following site configuration options require the server to be restarted for the changes to take effect:

auth.accessTokens
auth.sessionExpiry
git.cloneURLToRepositoryName
searchScopes
extensions
disablePublicRepoRedirects

Editing your site configuration if you cannot access the web UI

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:

docker exec -it --user=root $FRONTEND_CONTAINER sh -c 'apk add --no-cache && nano /home/sourcegraph/site-config.json'

Or if you prefer using a Vim editor:

docker exec -it $FRONTEND_CONTAINER sh -c 'vi ~/site-config.json'

Sourcegraph with Kubernetes

For Kubernetes deployments:

kubectl exec -it $FRONTEND_POD -- sh -c 'apk add --no-cache nano && nano ~/site-config.json'

Or if you prefer using a Vim editor:

kubectl exec -it $FRONTEND_POD -- sh -c 'vi ~/site-config.json'

Then simply save your changes (type ctrl+x and y to exit nano and save your changes). Your changes will be applied immediately in the same was as if you had made them through the web UI.

If you are still encountering issues

You can check the container logs to see if you have made any typos or mistakes in editing the configuration file. If you are still encountering problems, you can save the default site configuration that comes with Sourcegraph (below) or contact [email protected] with any questions you have.

{
	// The externally accessible URL for Sourcegraph (i.e., what you type into your browser)
	// This is required to be configured for Sourcegraph to work correctly.
	// "externalURL": "https://sourcegraph.example.com",

	// The authentication provider to use for identifying and signing in users.
	// Only one entry is supported.
	//
	// The builtin auth provider with signup disallowed (shown below) means that
	// after the initial site admin signs in, all other users must be invited.
	//
	// Other providers are documented at https://docs.sourcegraph.com/admin/auth.
	"auth.providers": [
		{
			"type": "builtin",
			"allowSignup": false
		}
	],

	"search.index.enabled": true
}