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

JSON
{
	"RedirectUnsupportedBrowser": false,
	"attribution.enabled": false,
	"attribution.gateway": {
		"accessToken": null,
		"endpoint": null
	},
	"attribution.mode": "permissive",
	"auth.accessRequest": {
		"enabled": true
	},
	"auth.accessTokens": {
		"allow": "all-users-create",
		"allowNoExpiration": false,
		"defaultExpirationDays": 90,
		"expirationOptionDays": [
			7,
			14,
			30,
			60,
			90
		]
	},
	"auth.allowedIpAddress": {
		"clientIpAddress": null,
		"enabled": false,
		"errorMessageTemplate": "Access from your IP address is not allowed.",
		"trustedClientIpAddress": null,
		"userIpAddress": null,
		"userIpRequestHeaders": null
	},
	"auth.enableUsernameChanges": false,
	"auth.lockout": {
		"consecutivePeriod": 3600,
		"failedAttemptThreshold": 5,
		"lockoutPeriod": 1800
	},
	"auth.maxSessionIdleDuration": "0",
	"auth.minPasswordLength": 12,
	"auth.passwordPolicy": {
		"enabled": false,
		"numberOfSpecialCharacters": 0,
		"requireAtLeastOneNumber": true,
		"requireUpperandLowerCase": true
	},
	"auth.passwordResetLinkExpiry": 14400,
	"auth.primaryLoginProvidersCount": 3,
	"auth.providers": [
		{
			"allowSignup": true,
			"type": "builtin"
		}
	],
	"auth.sessionExpiry": "2160h",
	"auth.unlockAccountLinkExpiry": 5,
	"auth.unlockAccountLinkSigningKey": null,
	"auth.userOrgMap": null,
	"authz.enforceForSiteAdmins": false,
	"batchChanges.autoDeleteBranch": false,
	"batchChanges.changesetsRetention": null,
	"batchChanges.containerRegistryAllowlist": null,
	"batchChanges.containerRegistryDenylist": null,
	"batchChanges.disableWebhooksWarning": false,
	"batchChanges.enabled": true,
	"batchChanges.enforceForks": false,
	"batchChanges.rejectUnverifiedCommit": false,
	"batchChanges.restrictToAdmins": false,
	"batchChanges.rolloutWindows": null,
	"batchChanges.templateLibrary.displayLimit": 20,
	"branding": {
		"brandName": "Sourcegraph",
		"dark": null,
		"disableSymbolSpin": false,
		"favicon": null,
		"light": null
	},
	"cloneProgress.log": false,
	"codeIntelAutoIndexing.allowGlobalPolicies": false,
	"codeIntelAutoIndexing.enabled": false,
	"codeIntelAutoIndexing.indexerMap": null,
	"codeIntelAutoIndexing.policyRepositoryMatchLimit": -1,
	"codeMonitors": {
		"concurrency": 4,
		"maxRuntime": 1,
		"pollInterval": "5m"
	},
	"cody.contextFilters": {
		"exclude": null,
		"include": null
	},
	"cody.enabled": false,
	"cody.permissions": true,
	"cody.restrictUsersFeatureFlag": false,
	"cody.serverSideContext": {
		"reranker": {
			"type": null
		}
	},
	"completions": {
		"accessToken": null,
		"azureChatModel": null,
		"azureCompletionModel": null,
		"azureUseDeprecatedCompletionsAPIForOldModels": true,
		"chatModel": null,
		"chatModelMaxTokens": 0,
		"completionModel": null,
		"completionModelMaxTokens": 0,
		"disableClientConfigAPI": false,
		"enabled": true,
		"endpoint": null,
		"fastChatModel": null,
		"fastChatModelMaxTokens": 0,
		"model": null,
		"perCommunityUserChatMonthlyInteractionLimit": 0,
		"perCommunityUserChatMonthlyLLMRequestLimit": 0,
		"perCommunityUserCodeCompletionsMonthlyInteractionLimit": 0,
		"perCommunityUserCodeCompletionsMonthlyLLMRequestLimit": 0,
		"perProUserChatDailyInteractionLimit": 0,
		"perProUserChatDailyLLMRequestLimit": 0,
		"perProUserCodeCompletionsDailyInteractionLimit": 0,
		"perProUserCodeCompletionsDailyLLMRequestLimit": 0,
		"perUserCodeCompletionsDailyLimit": 0,
		"perUserDailyLimit": 0,
		"provider": "sourcegraph",
		"smartContextWindow": "enabled",
		"user": null
	},
	"configFeatures": {
		"autoComplete": false,
		"chat": false,
		"chatVision": false,
		"commands": false
	},
	"contributorsDataEnabled": true,
	"corsOrigin": null,
	"debug.search.symbolsParallelism": 0,
	"defaultRateLimit": -1,
	"disableAutoCodeHostSyncs": false,
	"disableAutoGitUpdates": false,
	"disableFeedbackSurvey": false,
	"disableNonCriticalTelemetry": false,
	"disablePublicRepoRedirects": false,
	"dotcom": {
		"codyGateway": {
			"bigQueryDataset": null,
			"bigQueryGoogleProjectID": null,
			"bigQueryTable": null
		},
		"codyProConfig": {
			"samsBackendOrigin": "",
			"sscBackendOrigin": "",
			"sscBaseUrl": "https://accounts.sourcegraph.com/cody",
			"stripePublishableKey": null,
			"useEmbeddedUI": false
		},
		"enterprisePortal.enableProxies": true,
		"sams.clientID": null,
		"sams.clientSecret": null,
		"sams.server": null,
		"samsDev.clientID": null,
		"samsDev.clientSecret": null,
		"samsDev.server": "https://accounts.sgdev.org",
		"srcCliVersionCache": {
			"enabled": false,
			"github": {
				"repository": {
					"name": "src-cli",
					"owner": "sourcegraph"
				},
				"token": null,
				"uri": "https://github.com",
				"webhookSecret": null
			},
			"interval": "1h"
		}
	},
	"email.address": null,
	"email.senderName": "Sourcegraph",
	"email.smtp": null,
	"email.templates": {
		"resetPassword": null,
		"setPassword": null
	},
	"embeddings": {
		"accessToken": null,
		"dimensions": 0,
		"enabled": true,
		"endpoint": null,
		"excludeChunkOnError": true,
		"excludedFilePathPatterns": [
			".*ignore",
			".gitattributes",
			".mailmap",
			"*.csv",
			"*.svg",
			"*.xml",
			"__fixtures__/",
			"node_modules/",
			"testdata/",
			"mocks/",
			"vendor/"
		],
		"fileFilters": {
			"excludedFilePathPatterns": [
				".*ignore",
				".gitattributes",
				".mailmap",
				"*.csv",
				"*.svg",
				"*.xml",
				"__fixtures__/",
				"node_modules/",
				"testdata/",
				"mocks/",
				"vendor/"
			],
			"includedFilePathPatterns": null,
			"maxFileSizeBytes": 1000000
		},
		"incremental": true,
		"maxEmbeddingsPerRepo": 0,
		"minimumInterval": "24h",
		"model": null,
		"perCommunityUserEmbeddingsMonthlyLimit": 0,
		"perProUserEmbeddingsMonthlyLimit": 0,
		"policyRepositoryMatchLimit": "5000",
		"provider": null,
		"url": null
	},
	"encryption.keys": {
		"batchChangesCredentialKey": null,
		"cacheSize": 2048,
		"enableCache": false,
		"executorSecretKey": null,
		"externalServiceKey": null,
		"gitHubAppKey": null,
		"outboundWebhookKey": null,
		"userExternalAccountKey": null,
		"webhookKey": null,
		"webhookLogKey": null
	},
	"entitlements.completionCredits": {
		"mode": "disabled"
	},
	"executors.accessToken": null,
	"executors.batcheshelperImage": "sourcegraph/batcheshelper",
	"executors.batcheshelperImageTag": null,
	"executors.frontendURL": null,
	"executors.lsifGoImage": null,
	"executors.multiqueue": {
		"dequeueCacheConfig": {
			"batches": {
				"limit": 50,
				"weight": 4
			},
			"codeintel": {
				"limit": 250,
				"weight": 1
			}
		}
	},
	"executors.srcCLIImage": "sourcegraph/src-cli",
	"executors.srcCLIImageTag": null,
	"experimentalFeatures": {
		"batchChanges.enableForkNameSuffix": false,
		"batchChanges.enablePerforce": false,
		"codeintelSyntacticIndexing.enabled": false,
		"cody.auditLog": {
			"enabled": false
		},
		"codyContextIgnore": false,
		"commitGraphUpdates": {
			"defaultBranchOnly": null
		},
		"customGitFetch": null,
		"debug.log": {
			"extsvc.gitlab": false
		},
		"deepSearch.enabled": false,
		"deepSearch.model": "anthropic::2024-10-22::claude-sonnet-4-latest",
		"deepSearch.sharing.enabled": false,
		"enableGithubInternalRepoVisibility": false,
		"enablePermissionsWebhooks": false,
		"enableStorm": false,
		"eventLogging": "enabled",
		"gitServerPinnedRepos": null,
		"goPackages": "disabled",
		"insightsAlternateLoadingStrategy": false,
		"insightsBackfillerV2": true,
		"insightsDataRetention": true,
		"jvmPackages": "disabled",
		"languageDetection": {
			"graphQL": "useFileContents"
		},
		"npmPackages": "disabled",
		"pagure": "disabled",
		"passwordPolicy": {
			"enabled": true,
			"minimumLength": 12,
			"numberOfSpecialCharacters": 2,
			"requireAtLeastOneNumber": true,
			"requireUpperandLowerCase": true
		},
		"perforceChangelistMapping": "enabled",
		"pythonPackages": "disabled",
		"ranking": {
			"flushWallTimeMS": 500,
			"maxQueueMatchCount": -1,
			"maxQueueSizeBytes": -1,
			"maxReorderDurationMS": 0,
			"maxReorderQueueSize": 24,
			"repoScores": {}
		},
		"rateLimitAnonymous": 500,
		"rubyPackages": "disabled",
		"rustPackages": "disabled",
		"scipBasedAPIs": true,
		"search.index.branches": null,
		"search.index.query.contexts": false,
		"search.index.revisions": null,
		"search.sanitization": {
			"orgName": null,
			"sanitizePatterns": null
		},
		"searchJobs": false,
		"structuralSearch": "disabled",
		"subRepoPermissions": {
			"allowCodeInsights": false,
			"enabled": false,
			"enforceIPRestrictions": false,
			"ipParseCacheSize": 1000,
			"redactInaccessibleCommits": false,
			"rulesInterpretationMode": "unified",
			"userCacheSize": 1000,
			"userCacheTTLSeconds": 10
		},
		"tls.external": {
			"certificates": null,
			"insecureSkipVerify": false
		}
	},
	"externalURL": null,
	"git.cloneURLToRepositoryName": null,
	"gitHubApp": {
		"appID": null,
		"clientID": null,
		"clientSecret": null,
		"privateKey": null,
		"slug": null
	},
	"gitLongCommandTimeout": 7200,
	"gitMaxCodehostRequestsPerSecond": -1,
	"gitMaxConcurrentCleanups": 5,
	"gitMaxConcurrentClones": 5,
	"gitRecorder": {
		"ignoredGitCommands": [
			"show",
			"rev-parse",
			"log",
			"diff",
			"ls-tree"
		],
		"repos": null,
		"size": 10000
	},
	"gitUpdateInterval": null,
	"gitserver.diskUsageWarningThreshold": 90,
	"htmlBodyBottom": null,
	"htmlBodyTop": null,
	"htmlHeadBottom": null,
	"htmlHeadTop": null,
	"insights.aggregations.bufferSize": 500,
	"insights.aggregations.proactiveResultLimit": 50000,
	"insights.backfill.interruptAfter": 60,
	"insights.backfill.repositoryConcurrency": 3,
	"insights.backfill.repositoryGroupSize": 10,
	"insights.historical.worker.rateLimit": 20,
	"insights.historical.worker.rateLimitBurst": 20,
	"insights.maximumSampleSize": 30,
	"insights.query.worker.concurrency": 1,
	"insights.query.worker.rateLimit": 20,
	"insights.query.worker.rateLimitBurst": 20,
	"inventory": {
		"disableEnhancedLanguageDetection": false,
		"gitServerConcurrency": 4,
		"maxInventoryInMemory": 1000,
		"redisConcurrency": 20,
		"timeoutInMinutes": 5
	},
	"licenseKey": null,
	"log": {
		"auditLog": {
			"gitserverAccess": false,
			"graphQL": false,
			"internalTraffic": false,
			"severityLevel": null
		},
		"sentry": {
			"backendDSN": null,
			"codeIntelDSN": null,
			"dsn": null
		}
	},
	"lsifEnforceAuth": false,
	"maxReposToSearch": -1,
	"modelConfiguration": null,
	"notifications": null,
	"observability.alerts": null,
	"observability.captureSlowGraphQLRequestsLimit": 0,
	"observability.client": {
		"openTelemetry": {
			"endpoint": "/-/debug/otlp",
			"webVitalsInstrumentation": false
		}
	},
	"observability.logSlowGraphQLRequests": 0,
	"observability.logSlowSearches": 0,
	"observability.silenceAlerts": null,
	"observability.tracing": {
		"debug": false,
		"sampling": "selective",
		"type": "opentelemetry",
		"urlTemplate": null
	},
	"organizationInvitations": {
		"expiryTime": 48,
		"signingKey": null
	},
	"outboundRequestLogLimit": 50,
	"own.background.repoIndexConcurrencyLimit": 5,
	"own.background.repoIndexRateBurstLimit": 5,
	"own.background.repoIndexRateLimit": 20,
	"own.bestEffortTeamMatching": true,
	"parentSourcegraph": {
		"url": "https://sourcegraph.com"
	},
	"permissions.syncJobCleanupInterval": 3600,
	"permissions.syncJobsHistorySize": 5,
	"permissions.syncOldestRepos": 100,
	"permissions.syncOldestUsers": 100,
	"permissions.syncReposBackoffSeconds": 900,
	"permissions.syncReposMaxConcurrency": 5,
	"permissions.syncScheduleInterval": 60,
	"permissions.syncUsersBackoffSeconds": 900,
	"permissions.syncUsersMaxConcurrency": 5,
	"permissions.userMapping": {
		"bindID": "email",
		"enabled": true
	},
	"productResearchPage.enabled": true,
	"rateLimits": {
		"graphQLMaxAliases": 500,
		"graphQLMaxDepth": 30,
		"graphQLMaxDuplicateFieldCount": 500,
		"graphQLMaxFieldCount": 500000,
		"graphQLMaxUniqueFieldCount": 500
	},
	"redactOutboundRequestHeaders": false,
	"repoConcurrentExternalServiceSyncers": 3,
	"repoListUpdateInterval": 1,
	"repoPurgeWorker": {
		"deletedTTLMinutes": 60,
		"intervalMinutes": 15
	},
	"scim.authToken": "",
	"scim.identityProvider": "STANDARD",
	"search.index.shardConcurrency": 0,
	"search.index.symbols.enabled": false,
	"search.largeFiles": null,
	"search.limits": {
		"commitDiffMaxRepos": 50,
		"commitDiffWithTimeFilterMaxRepos": 10000,
		"maxRepos": -1,
		"maxTimeoutSeconds": "60"
	},
	"ssc.apiBaseUrl": "https://accounts.sourcegraph.com/cody/api",
	"ssc.samsHostName": "accounts.sourcegraph.com",
	"syntaxHighlighting": {
		"engine": {
			"default": null,
			"overrides": null
		},
		"languages": {
			"extensions": null,
			"patterns": null
		},
		"symbols": {
			"engine": null
		}
	},
	"telemetry": {
		"disableLocalEventLogs": false
	},
	"update.channel": "release",
	"webhook.logging": {
		"enabled": false,
		"retention": "72h"
	}
}

Configuration Notes

Critical Restart Requirements

The following configuration options require a server restart to take effect:

  • auth.providers - Changes to authentication providers
  • externalURL - External URL modifications
  • insights.query.worker.concurrency - Code Insights query worker settings
  • insights.commit.indexer.interval - Code Insights indexer intervals
  • permissions.syncUsersMaxConcurrency - Permission sync concurrency limits

Configuration Dependencies

Several configuration options depend on each other:

  • corsOrigin is required when using native integrations for Phabricator, GitLab, or Bitbucket Server
  • email.address and email.smtp must both be configured for transactional email functionality
  • executors.accessToken requires at least 20 characters for executor authentication
  • licenseKey is necessary to activate Enterprise features

Performance Considerations

  • gitMaxConcurrentClones controls clone concurrency per gitserver - increase for better performance on powerful hardware
  • permissions.syncUsersMaxConcurrency and permissions.syncReposMaxConcurrency affect authorization sync performance
  • insights.query.worker.concurrency and related rate limits impact Code Insights performance
  • search.limits.maxRepos prevents resource exhaustion from overly broad searches

Security Considerations

Authentication & Authorization

  • Never set auth.enableUsernameChanges to true if using external authentication or username-based repository permissions
  • authz.enforceForSiteAdmins should be true in environments with strict access controls
  • auth.sessionExpiry should be shortened in high-security environments
  • auth.passwordPolicy should be configured to enforce strong password requirements

Token Management

  • executors.accessToken must be securely generated and stored
  • auth.unlockAccountLinkSigningKey should be a strong, randomly generated key
  • organizationInvitations.signingKey requires secure key generation
  • scim.authToken should be treated as a high-privilege credential

Encryption & Privacy

  • encryption.keys configuration must use secure key management practices
  • redactOutboundRequestHeaders is automatically enabled in production environments
  • Webhook secrets in external service configurations should be randomly generated

Network Security

  • corsOrigin should be strictly limited to trusted domains
  • externalURL must use HTTPS in production environments
  • observability.tracing configurations may expose sensitive data - configure carefully

Common Examples

Basic Authentication Setup

JSON
{
  "externalURL": "https://sourcegraph.example.com",
  "auth.providers": [
    {
      "type": "builtin",
      "allowSignup": false
    }
  ]
}

Email Configuration

JSON
{
  "email.address": "noreply@example.com",
  "email.smtp": {
    "host": "smtp.example.com",
    "port": 587,
    "username": "smtp-user",
    "password": "smtp-password",
    "authentication": "PLAIN"
  }
}

Executor Configuration

JSON
{
  "executors.accessToken": "your-super-secret-access-token-here",
  "executors.frontendURL": "https://sourcegraph.example.com"
}

Code Intelligence Optimization

JSON
{
  "codeIntelAutoIndexing.enabled": true,
  "codeIntelAutoIndexing.allowGlobalPolicies": false,
  "codeIntelAutoIndexing.policyRepositoryMatchLimit": 1000
}

Search Performance Tuning

JSON
{
  "search.limits": {
    "maxRepos": 500,
    "maxTimeoutSeconds": 60,
    "commitDiffMaxRepos": 100
  },
  "search.largeFiles": [
    "package-lock.json",
    "yarn.lock",
    "go.sum"
  ]
}

Batch Changes Configuration

JSON
{
  "batchChanges.enabled": true,
  "batchChanges.restrictToAdmins": false,
  "batchChanges.rolloutWindows": [
    {
      "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
      "start": "09:00",
      "end": "17:00",
      "rate": "5/hour"
    }
  ]
}

Best Practices

Initial Setup

  1. Always configure externalURL first - This is required for Sourcegraph to function correctly
  2. Set up authentication before adding users - Use allowSignup: false for controlled user onboarding
  3. Configure email early - Required for password resets and notifications
  4. Plan your license key deployment - Enterprise features require valid licensing

Performance Optimization

  1. Monitor resource usage - Adjust concurrency limits based on system capacity
  2. Tune search limits - Prevent resource exhaustion with appropriate maxRepos settings
  3. Configure git update intervals - Balance freshness with system load using gitUpdateInterval
  4. Optimize permission syncing - Adjust sync intervals and concurrency based on user count

Security Hardening

  1. Use strong authentication - Implement SAML/OIDC instead of built-in auth for production
  2. Enable authorization enforcement - Set authz.enforceForSiteAdmins in strict environments
  3. Secure external communications - Use HTTPS for all external URLs and webhooks
  4. Implement proper key management - Use secure key generation and rotation practices

Operational Excellence

  1. Plan for restarts - Schedule configuration changes requiring restarts during maintenance windows
  2. Monitor configuration drift - Regularly audit settings against organizational policies
  3. Document customizations - Maintain records of non-default configuration choices
  4. Test in staging - Validate complex configuration changes in non-production environments

Backup & Recovery

  1. Backup site-config.json - Include configuration in disaster recovery procedures
  2. Version control settings - Track configuration changes in source control
  3. Document dependencies - Maintain clear documentation of configuration relationships
  4. Test recovery procedures - Regularly verify ability to restore from backups

Accessing global settings

Global settings should rarely need to be accessed. You will need to direct database access to change this setting.

To find the current global settings, use the following SQL query:

SQL
SELECT * FROM settings WHERE user_id IS null and org_id IS null ORDER BY id DESC;

This will return a history of all global settings changes, the highest id being the latest Next, you can update the content column to either {} to reset global settings or to the desired JSON object.

SQL
UPDATE settings SET content = '{}' WHERE id IS <id>;