Settings

Settings provide the ability to customize and control the Sourcegraph UI and user-specific features. They do not configure operational aspects of the instance (which are set in the site configuration).

Settings can be set at the global level (by site admins), the organization level (by organization members), and at the individual user level.

Settings-Cascade

Editing global settings (for site admins)

Global settings are found in Site admin > Global settings while links to organization and user settings are found in the user dropdown menu.

After setting or changing certain values in Site admin > Global settings the frontend will restart automatically or you might be asked to restart the frontend for the changes to take effect. In case of a Kubernetes deployment this can be done as follows:

SHELL
bash
kubectl delete pods -l app=sourcegraph-frontend

Reference

Settings options and their default values are shown below.

admin/config/settings.schema.json

JSON
{
	"alerts.hideObservabilitySiteAlerts": true,
	"alerts.showMajorMinorUpdates": true,
	"alerts.showPatchUpdates": true,
	"basicCodeIntel.globalSearchesEnabled": false,
	"basicCodeIntel.includeArchives": false,
	"basicCodeIntel.includeForks": false,
	"basicCodeIntel.indexOnly": false,
	"basicCodeIntel.unindexedSearchTimeout": 0,
	"codeIntel.disableRangeQueries": false,
	"codeIntel.disableSearchBased": false,
	"codeIntel.mixPreciseAndSearchBasedReferences": false,
	"codeIntel.traceExtension": false,
	"cody.notices": null,
	"experimentalFeatures": {
		"batchChangesExecution": true,
		"boostRelevantRepositories": true,
		"clientSearchResultRanking": "by-zoekt-ranking",
		"codeInsightsCompute": false,
		"codeInsightsRepoUI": "single-search-query",
		"disableOrderBySimilarity": false,
		"enableLazyBlobSyntaxHighlighting": true,
		"enableLazyFileResultSyntaxHighlighting": true,
		"enableSearchFilePrefetch": true,
		"enableSidebarFilePrefetch": true,
		"fuzzyFinder": false,
		"fuzzyFinderActions": false,
		"fuzzyFinderAll": false,
		"fuzzyFinderCaseInsensitiveFileCountThreshold": 25000,
		"fuzzyFinderNavbar": false,
		"fuzzyFinderRepositories": false,
		"fuzzyFinderSymbols": false,
		"goCodeCheckerTemplates": false,
		"keywordSearch": true,
		"newSearchNavigationUI": false,
		"newSearchResultFiltersPanel": false,
		"newSearchResultsUI": true,
		"proactiveSearchResultsAggregations": true,
		"searchContextsQuery": false,
		"searchQueryInput": "v1",
		"searchResultsAggregations": false,
		"showCodeMonitoringLogs": false,
		"symbolKindTags": false
	},
	"fileSidebarVisibleByDefault": true,
	"history.defaultPageSize": 0,
	"history.preferAbsoluteTimestamps": false,
	"insights.aggregations.extendedTimeout": 55,
	"motd": null,
	"notices": null,
	"openInEditor": {
		"custom.urlPattern": null,
		"editorIds": null,
		"jetbrains.forceApi": null,
		"projectPaths.default": null,
		"projectPaths.linux": null,
		"projectPaths.mac": null,
		"projectPaths.windows": null,
		"replacements": null,
		"vscode.isProjectPathUNCPath": false,
		"vscode.remoteHostForSSH": null,
		"vscode.useInsiders": false,
		"vscode.useSSH": false
	},
	"orgs.allMembersBatchChangesAdmin": false,
	"perforce.codeHostToSwarmMap": {},
	"quicklinks": null,
	"search.contextLines": 1,
	"search.defaultCaseSensitive": false,
	"search.defaultMode": null,
	"search.defaultPatternType": null,
	"search.displayLimit": 1500,
	"search.hideSuggestions": false,
	"search.includeArchived": false,
	"search.includeForks": false,
	"search.scopes": null,
	"siteWideSearchContext": null
}

Configuration Notes

Settings Hierarchy and Inheritance

Settings follow a cascade model where more specific settings override general ones:

  1. User settings - highest priority, affects individual users only
  2. Organization settings - medium priority, affects all organization members
  3. Global settings - lowest priority, affects all users on the instance

Frontend Restart Requirements

Some settings changes require a frontend restart to take effect:

  • Changes to global settings may trigger automatic frontend restarts
  • In Kubernetes deployments, manually restart frontend pods: kubectl delete pods -l app=sourcegraph-frontend

Deprecated Settings

Several settings are deprecated and should be migrated:

  • motd - Replace with notices for better functionality and styling options
  • quicklinks - Will be removed in future versions
  • search.savedQueries - Functionality integrated into search interface

Performance Impact Settings

  • search.displayLimit affects initial search result loading - higher values increase memory usage
  • basicCodeIntel.globalSearchesEnabled can impact performance on large instances
  • insights.aggregations.extendedTimeout extends query timeouts but may increase load

Security Considerations

User Privacy and Data Protection

  • Global settings visibility - Global settings are visible to all users; avoid including sensitive information
  • Notice content - Notices are displayed to all users; ensure content is appropriate for your organization
  • Search behavior - Default search settings affect what users can discover across repositories

Access Control Configuration

  • orgs.allMembersBatchChangesAdmin grants administrative privileges to all organization members - use carefully
  • basicCodeIntel.includeArchives and basicCodeIntel.includeForks may expose archived or forked repositories users shouldn't access
  • Settings should align with repository permission policies to prevent unauthorized access

Code Intelligence Security

  • codeIntel.disableSearchBased may expose code patterns through search-based fallbacks
  • codeIntel.mixPreciseAndSearchBasedReferences combines precise and search results - ensure both are appropriate
  • Trace logging (codeIntel.traceExtension) may expose code content in logs

Common Examples

Basic User Experience Configuration

JSON
{
  "fileSidebarVisibleByDefault": true,
  "search.defaultCaseSensitive": false,
  "search.defaultPatternType": "keyword",
  "search.displayLimit": 1500
}

Search Optimization

JSON
{
  "search.contextLines": 3,
  "search.includeArchived": false,
  "search.includeForks": false,
  "search.hideSuggestions": false,
  "basicCodeIntel.globalSearchesEnabled": true,
  "basicCodeIntel.unindexedSearchTimeout": 30000
}

Code Intelligence Configuration

JSON
{
  "codeIntel.disableRangeQueries": false,
  "codeIntel.disableSearchBased": false,
  "codeIntel.mixPreciseAndSearchBasedReferences": true,
  "basicCodeIntel.indexOnly": false
}

Organization Batch Changes Setup

JSON
{
  "orgs.allMembersBatchChangesAdmin": false
}

Notices and Alerts Configuration

JSON
{
  "notices": [
    {
      "message": "📢 Scheduled maintenance window: **Saturday 2-4 PM UTC**",
      "location": "top",
      "dismissible": true,
      "variant": "warning"
    }
  ],
  "alerts.showMajorMinorUpdates": true,
  "alerts.showPatchUpdates": false,
  "alerts.hideObservabilitySiteAlerts": false
}

History and Interface Preferences

JSON
{
  "history.defaultPageSize": 50,
  "history.preferAbsoluteTimestamps": false,
  "fileSidebarVisibleByDefault": true
}

Code Insights Extended Configuration

JSON
{
  "insights.aggregations.extendedTimeout": 45
}

Best Practices

Settings Management Strategy

  1. Use global settings sparingly - Only configure settings that should apply to all users
  2. Leverage organization settings - Configure team-specific preferences at the organization level
  3. Document setting changes - Maintain records of why specific settings were configured
  4. Test setting changes - Verify settings work as expected before applying organization-wide

User Experience Optimization

  1. Configure sensible defaults - Set search and display preferences that work for most users
  2. Enable helpful features - Turn on code intelligence features unless they cause performance issues
  3. Minimize distractions - Use notices judiciously to avoid alert fatigue
  4. Respect user preferences - Allow users to override organization settings when appropriate

Performance Considerations

  1. Monitor search performance - Adjust displayLimit and timeout settings based on instance performance
  2. Balance code intelligence features - Enable features that provide value without overwhelming the system
  3. Consider repository scale - Disable global searches on very large instances if needed
  4. Test timeout settings - Ensure Code Insights timeouts are appropriate for your query complexity

Maintenance and Updates

  1. Review deprecated settings - Regularly audit and migrate away from deprecated configurations
  2. Update alerting preferences - Configure update notifications based on your maintenance schedule
  3. Validate settings hierarchy - Ensure organization and global settings work together as intended
  4. Plan for setting changes - Coordinate setting updates with users when they affect user experience

Communication Best Practices

  1. Use clear notice messaging - Write notices that clearly communicate important information
  2. Choose appropriate notice styling - Use warning/danger variants for critical information
  3. Make notices actionable - Include links to relevant documentation or actions users should take
  4. Time-bound temporary notices - Remove notices when they're no longer relevant

Additional details on settings

Notices

Notices can be added in global, organization, or user settings. The notices setting is a list of notice configurations with the following options:

  1. message: the markdown copy to be displayed in the banner
  2. location: where the banner will be shown. Either on the home page with "home" or at the top of the page with "top"
  3. dismissible (optional): boolean (true or false). If true, users will be able to close the notice and not see it again. If false, it will persist on the instance until the configuration is removed.
  4. variant (optional): one of "primary", "secondary", "success", "danger", "warning", "info", "note" the style of the notice. Although specifics such as color depend on the theme in general danger or primary will draw more attention than secondary or note. The default style depends on the location of the notice.
  5. styleOverrides (optional): a configuration object with the following elements:
    1. backgroundColor (optional): a hexadecimal color code for forcing a specific background color.
    2. textColor (optional): a hexadecimal color code for forcing a specific text color.
    3. textCentered (optional): boolean (true or false). If true, the text will be centered in the banner.

Example settings:

JSON
"notices": [
  {
    "message": "Your important message here! [Include a link for more information](http://example.com).",
    "location": "top",
    "dismissible": true,
    "variant": "danger",
    "styleOverrides": {
      "styleOverrides": {
        "backgroundColor": "#7f1d1d",
        "textColor": "#fecaca",
        "textCentered": true
      }
    }
  }
]