Sourcegraph DocsSourcegraph Docs
Changelog↗
Theme
  1. Docs
  2. self-hosted
  3. private-network

Private network configuration

Overview

A private network is your organization's secure, internal network space - separated from the public internet. Think of it as your company's own protected environment where internal systems can communicate safely, keeping your sensitive data and operations shielded from external access.

When deploying self-hosted Sourcegraph instances in private networks with specific compliance and policy requirements, additional configuration may be required to ensure all networking features function correctly. The reasons for applying the following configuration options depend on the specific functionality of the Sourcegraph service and the unique network and infrastructure requirements of the organization.

The following Sourcegraph services initiate outbound connections to external services:

  • executor: Sourcegraph Executor batch change or precise indexing jobs may need to connect to services hosted within an organization's private network
  • frontend: The frontend service communicates externally when connecting to:
    • External auth providers
    • Sending telemetry data
    • Testing code host connections
    • Connecting to externally hosted Sourcegraph services
    • Connecting to external LLM providers with Cody
  • gitserver: Executes git commands against externally hosted code hosts
  • migrator: Connects to Postgres instances (which may be externally hosted) to process database migrations
  • worker: Sourcegraph Worker background jobs that may require establishing connections to services hosted within an organization's private network

Outbound access to Sourcegraph services

Sourcegraph makes requests to https://services.sourcegraph.com for key product capabilities.

To ensure a smooth experience, instances must allow outbound TCP port 443 to 34.36.231.254, with HTTPS and HTTP/2 gRPC support through your firewall or proxy. For hostname-based filtering, allow services.sourcegraph.com. Keep the hostname for TLS; do not replace it with the IP address. No inbound firewall rule is required.

HTTP proxy configuration

Dedicated proxy for Sourcegraph services

Set SERVICES_GATEWAY_PROXY to route pings, telemetry, and licensing traffic through a dedicated proxy, independently of code-host traffic and model inference. This applies to the clients described in outbound access to Sourcegraph services, including their endpoint overrides.

  1. Set the following environment variable on every frontend replica, with the same value on each replica:

    SH
    SERVICES_GATEWAY_PROXY=http://proxy.example.com:3128

  2. Restart the frontend replicas. Frontend validates the URL and distributes it to consumers through ServiceConnections, not site configuration. Do not set this variable on other services: consumers ignore their local SERVICES_GATEWAY_PROXY and use the value distributed by frontend.

  3. Expect consuming services to restart when the distributed value changes, including when you remove the proxy or change its credentials. Consumers exit so their process supervisor can restart them and recreate cached HTTP clients and gRPC connections with the updated route.

The dedicated proxy supports HTTP CONNECT, with optional Basic authentication in the URL, for example http://username:password@proxy.example.com:3128. URL-encode special characters in credentials. Use an http:// proxy URL with no query or fragment and no path other than an optional trailing slash. HTTPS-to-proxy and SOCKS proxies are not supported.

HTTPS and gRPC connections retain TLS to the destination through the CONNECT tunnel. The connection to the proxy itself is not TLS-encrypted, so protect that network path, especially when using Basic authentication. The proxy must allow CONNECT to the destination and carry HTTP/2 gRPC traffic through the tunnel.

SERVICES_GATEWAY_PROXY takes precedence over all standard proxy settings, including NO_PROXY, for these clients. This also applies to endpoint overrides, including localhost overrides. If the proxy is unreachable or rejects a connection, the request fails; it does not fall back to a direct connection. Other outbound clients do not use this dedicated proxy.

Standard process-local proxy settings

When SERVICES_GATEWAY_PROXY is unset or empty, gateway clients use standard Go HTTP/gRPC proxy selection from the environment of each process making the request:

  • HTTPS_PROXY selects a proxy for HTTPS requests and gRPC connections. Its value can be an http:// URL for an HTTP CONNECT proxy.
  • HTTP_PROXY selects a proxy for HTTP requests. Setting it alone does not proxy HTTPS or gRPC traffic.
  • NO_PROXY excludes matching destinations from standard proxy routing.

The lowercase forms (https_proxy, http_proxy, and no_proxy) are also supported; the uppercase value takes precedence when both are set. These variables are process-local and are not distributed by frontend. Set them on each service that needs them, including frontend and worker, and restart the affected services after changes.

Without the dedicated proxy, gateway HTTP clients use the internal HTTP client for endpoint hostnames localhost and 127.0.0.1, including pings endpoint overrides. Standard proxy selection also retains Go/gRPC's localhost and loopback exclusions; do not rely on HTTPS_PROXY to proxy those destinations.

Use the example override file for your deployment method to configure standard proxy variables:

  • Kubernetes Helm
  • Docker Compose

Docker networking configuration

If there is an IP conflict on between the host network and the Docker network, you may need to configure the docker CIDR range in the docker-compose override file.

Additional information on docker networking can be found here:

  • Docker networking overview
  • Networking in Compose

Trusting TLS certificates using internal PKI

If your organization uses internal Public Key Infrastructure to manage TLS certificates, you may need to configure your Sourcegraph instance to trust your internal Root Certificate Authorities, so your instance can connect to other internal services, ex. code hosts, authentication providers, etc.

This method offers several advantages:

  • Works consistently across both Cloud and self-hosted deployments
  • Requires minimal configuration changes
  • Can be managed entirely through the web UI
  • Maintains certificates in a centralized location
  • Aligns with enterprise PKI best practices

The configuration process involves identifying and adding the public key of your organization's root Certificate Authority (CA) to Sourcegraph's advanced configuration. This approach is particularly efficient because:

  • Root CA certificates typically have long expiration periods (often measured in years)
  • A single root CA certificate usually covers multiple internal services
  • The configuration can be managed without container modifications or filesystem changes

Obtain the certificate chain

Use the OpenSSL command to extract the certificate chain from your code host. Replace the domain and port with your internal code host's values:

BASH
openssl s_client -showcerts -connect example.com:8443 \
-nameopt lname < /dev/null > certs.log 2>&1

Identify the root certificate

In the generated certs.log file, locate the root CA certificate:

Certificate chains typically include 3 certificates:

  • Root certificate authority (depth=2)
  • Intermediate certificate authority (depth=1)
  • Server (leaf) certificate (depth=0)

The last certificate in the chain will be the root CA certificate and will typically have:

  • A long expiration period (years)
  • A descriptive common name (e.g., "Enterprise Root CA 2023")

Example root CA certificate for github.com:

TEXT
Connecting to 140.82.114.3
depth=2 countryName=US, stateOrProvinceName=New Jersey, localityName=Jersey City, organizationName=The USERTRUST Network, commonName=USERTrust ECC Certification Authority
verify return:1
depth=1 countryName=GB, stateOrProvinceName=Greater Manchester, localityName=Salford, organizationName=Sectigo Limited, commonName=Sectigo ECC Domain Validation Secure Server CA
verify return:1
depth=0 commonName=github.com
verify return:1
CONNECTED(00000005)
---
...
 2 s:countryName=US, stateOrProvinceName=New Jersey, localityName=Jersey City, organizationName=The USERTRUST Network, commonName=USERTrust ECC Certification Authority
   i:countryName=GB, stateOrProvinceName=Greater Manchester, localityName=Salford, organizationName=Comodo CA Limited, commonName=AAA Certificate Services
   a:PKEY: id-ecPublicKey, 384 (bit); sigalg: RSA-SHA384
   v:NotBefore: Mar 12 00:00:00 2019 GMT; NotAfter: Dec 31 23:59:59 2028 GMT
-----BEGIN CERTIFICATE-----
MII...c=
-----END CERTIFICATE-----

Format the certificate

Once you've identified the root CA certificate:

  • Extract the certificate content including the BEGIN and END markers.
  • Format the certificate for the advanced configuration:
    • Replace newlines with \n characters
    • Enclose the entire certificate in double quotes
    • Add a trailing comma

The following command can be used to easily obtain, extract, and format the root certificate from a 3 certificate chain. Be sure to adjust the hostname and port to match your internal code host. If your certificate chain is of a different depth, adjust the awk command accordingly. awk '/BEGIN CERTIFICATE/{i++} i==X'

BASH
openssl s_client -showcerts -connect example.com:8443 \
-nameopt lname < /dev/null 2>&1 \
| awk '/BEGIN CERTIFICATE/,/END CERTIFICATE/' \
| awk '/BEGIN CERTIFICATE/{i++} i==2' \
| awk '{printf "%s\\n", $0}' | sed 's/\\n$//' \
| awk '{print "\"" $0 "\","}'

Add the certificate to the advanced configuration

Add the formatted certificate to your Sourcegraph advanced configuration.

JSON
{
	"tls.external": {
		"certificates": [
			"-----BEGIN CERTIFICATE-----\naZ...==\n-----END CERTIFICATE-----"
		]
	}
}

For organizations with multiple root CAs (uncommon), additional certificates can be added to the array:

JSON
{
	"tls.external": {
		"certificates": [
			"-----BEGIN CERTIFICATE-----\naZ...==\n-----END CERTIFICATE-----",
			"-----BEGIN CERTIFICATE-----\nMI...I7\n-----END CERTIFICATE-----"
		]
	}
}

Validation of certificate configuration

These steps confirms that configuring the root CA certificate through tls.external is sufficient for all standard Sourcegraph operations that require secure connections to internal services.

  1. Code host connectivity

    • Verify using the UI "Test Connection" button
    • Trigger validate completed sync jobs
      Executed by: frontend service

  2. Repository operations

    • Verify individual repository synchronization
    • Verify cloning operations
      Executed by: gitserver service

  3. Permission synchronization

    • Verify user-centric permission sync jobs
      Executed by: worker service

Repository-centric permission sync jobs are expected to behave identically, as they use the same underlying TLS configuration mechanisms.

Recommended best practices

  • Only include root CA certificates, not intermediate or server certificates.
  • Avoid using insecureSkipVerify: true and add TLS certificates if needed, as it bypasses important security checks.
  • Document certificate sources and expiration dates in your organization's runbooks.
  • Plan for certificate rotation well before root CA expiration.
  • Most enterprises use a single root CA, so adding one certificate often covers all internal services.
  • Keep the certificate list minimal and well-maintained.

On this page

  1. Private network configuration

    1. Overview
    1. Outbound access to Sourcegraph services
    1. HTTP proxy configuration
    1. Docker networking configuration
    1. Trusting TLS certificates using internal PKI
Edit this page on GitHub
View as Markdown