diff --git a/AGENTS.md b/AGENTS.md index 99031fe40..354f36a6d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,20 @@ # Sourcegraph Docs - Agent Instructions +## Documentation style + +- Write long-lived feature and configuration docs in the present tense for the + behavior readers will use when the docs are published. Avoid time-relative + wording such as "upcoming", "new", or "now" that requires later cleanup. +- PRs for unreleased behavior can be ready for review. Coordinate merge timing + with the relevant release or weekly update, and record that dependency in the + PR description, not in customer prose. +- Describe the current behavior concisely. Put release transitions and old/new + comparisons in upgrade notes rather than permanent feature docs. Retain + version-specific guidance only when readers still need it to use or upgrade + supported releases. +- Number ordered Markdown lists sequentially (`1.`, `2.`, `3.`), rather than + writing every item as `1.`. + ## Build Commands - **Type Check**: `npx tsc --noEmit` diff --git a/docs/admin/architecture.mdx b/docs/admin/architecture.mdx index 12863e98d..1faecc190 100644 --- a/docs/admin/architecture.mdx +++ b/docs/admin/architecture.mdx @@ -276,6 +276,16 @@ Repository permissions are mirrored from code hosts to Sourcegraph by default. T ## Supporting features +### Connections to Sourcegraph-managed services + +Sourcegraph instances connect to the services gateway at `https://services.sourcegraph.com` to: + +1. Send pings and telemetry events, and check for product updates. See [Analytics and telemetry](#analytics-and-telemetry). +2. [Verify licenses](/admin/licensing/). +3. Check credit/quota availability and report consumption to [Enterprise Portal](/admin/enterprise-portal#credits). + +For self-hosted firewall and proxy requirements, see [outbound access to Sourcegraph services](/self-hosted/private-network#outbound-access-to-sourcegraph-services). Other enabled features and integrations may require additional external destinations. + ### Model Provider The **Sourcegraph Model Provider** is the default and recommended way to configure AI features like Deep Search and Cody. Through this service, we provide zero-configuration access to state-of-the-art models from various LLM providers, including Anthropic and OpenAI, with enterprise-grade [privacy and security](/model-provider#privacy-and-security). diff --git a/docs/admin/enterprise-portal.mdx b/docs/admin/enterprise-portal.mdx index ef949b0f1..30f05dc69 100644 --- a/docs/admin/enterprise-portal.mdx +++ b/docs/admin/enterprise-portal.mdx @@ -37,6 +37,8 @@ Subscription admins can view [Sourcegraph Analytics](/analytics) for the subscri Subscription admins can view credit balances and rates for metered services, including [Deep Search](/deep-search) and [Agentic Batch Changes](/agentic-batch-changes), on the **Credits** page. This replaces the former Deep Search usage monitoring page and shows subscription-wide consumption, not an individual user's usage. +Self-hosted instances need outbound connectivity to Enterprise Portal through the services gateway for credit/quota checks and consumption reporting. Before using metered services, configure the [required outbound access](/self-hosted/private-network#outbound-access-to-sourcegraph-services), including IP allowlisting if your network restricts egress. + 1. [Sign in to Enterprise Portal](#accessing-sourcegraph-enterprise-portal) as a subscription admin. 2. Select your subscription. 3. Select **Credits** in the subscription navigation. diff --git a/docs/admin/pings.mdx b/docs/admin/pings.mdx index 867d0d661..5613b3497 100644 --- a/docs/admin/pings.mdx +++ b/docs/admin/pings.mdx @@ -1,6 +1,6 @@ # Pings -Sourcegraph periodically sends a ping to `pings.sourcegraph.com` to help our product and customer teams. It sends only the high-level, aggregated data below. It never sends code, repository names, usernames, or any other specific data. To learn more, go to the **Administration > Pings** page on your instance (the URL is `https://sourcegraph.example.com/site-admin/pings`). +Sourcegraph periodically sends a ping to `services.sourcegraph.com` to help our product and customer teams. It sends only the high-level, aggregated data below. It never sends code, repository names, usernames, or any other specific data. To learn more, go to the **Administration > Pings** page on your instance (the URL is `https://sourcegraph.example.com/site-admin/pings`). Sourcegraph will also periodically perform a license verification check, to verify the validity of the configured Sourcegraph license. Tampering with these checks, or preventing them from occurring, will cause Sourcegraph to disable many features until a successful check is completed. Certain Enterprise licenses can request to be exempt from these license verification checks. @@ -202,7 +202,7 @@ Sourcegraph aggregates usage and performance metrics for some product features i ## Allowlist IPs / CIDR Ranges for Sourcegraph -Refer to the [Telemetry docs](/admin/telemetry) for the list of ranges to allowlist. +Refer to [outbound access to Sourcegraph services](/self-hosted/private-network#outbound-access-to-sourcegraph-services) for the destinations, ports, and protocols to allow. ## Using an HTTP proxy for ping requests @@ -212,15 +212,7 @@ Be sure to update the environment variable like so : `TELEMETRY_HTTP_PROXY:"http ## Connections to Sourcegraph-managed services -Sourcegraph only connects to Sourcegraph-managed services for three purposes: - -1. The pings described above are sent, in order to: - - Check for new product updates. - - Send [anonymous, non-specific, aggregate metrics](#pings) back to Sourcegraph.com (see the full list above). -1. [Verify](/admin/licensing/) the validity of the configured Sourcegraph license. -1. Legacy Sourcegraph extensions are fetched from Sourcegraph.com`s extension registry. - -There are no other automatic external connections to Sourcegraph.com (or any other site on the internet). +See [Connections to Sourcegraph-managed services](/admin/architecture#connections-to-sourcegraph-managed-services) in the architecture overview. ## Connections to Sourcegraph.com via Cody app diff --git a/docs/admin/telemetry/index.mdx b/docs/admin/telemetry/index.mdx index 79c78d1cf..91453fbaa 100644 --- a/docs/admin/telemetry/index.mdx +++ b/docs/admin/telemetry/index.mdx @@ -47,9 +47,7 @@ You can reach out to support@sourcegraph.com for additional information about ho ## Allowlist IPs / CIDR ranges for Sourcegraph -- For `pings.sourcegraph.com`, allowlist the IP address: `34.36.231.254` -- For `telemetry-gateway.sourcegraph.com`, allowlist the IP address: `34.107.157.31` -- For `sourcegraph.com`, allowlist the full [Cloudflare IP ranges](https://www.cloudflare.com/ips/) +See [outbound access to Sourcegraph services](/self-hosted/private-network#outbound-access-to-sourcegraph-services) for the services gateway's IP, hostname, and protocol requirements. ## Architecture diff --git a/docs/self-hosted/private-network.mdx b/docs/self-hosted/private-network.mdx index bf77f6df0..f7431f9cc 100644 --- a/docs/self-hosted/private-network.mdx +++ b/docs/self-hosted/private-network.mdx @@ -9,7 +9,7 @@ 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 is a list of Sourcegraph services that initiate outbound connections to external services. Sourcegraph services not included in this list can be assumed to only connect to services within the Sourcegraph deployment's network segment: +The following [Sourcegraph services](/admin/architecture) initiate outbound connections to external services: - **executor**: Sourcegraph [Executor](/self-hosted/executors/) batch change or precise indexing jobs may need to connect to services hosted within an organization's private network @@ -24,6 +24,12 @@ The following is a list of Sourcegraph services that initiate outbound connectio - **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](/admin/architecture#connections-to-sourcegraph-managed-services). + +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 All Sourcegraph services respect the conventional `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables for