ci/hostnames: Add PR check for example hostnames

.github/workflows/check-hostnames.yml

@@ -0,0 +1,22 @@
+name: Example hostnames
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'dev/check-hostnames.mjs'
+      - '.github/workflows/check-hostnames.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  check-hostnames:
+    name: Canonical example hostnames
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version-file: .tool-versions
+      - run: node dev/check-hostnames.mjs

dev/check-hostnames.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+
+/**
+ * Example hostname checker for MDX documentation files.
+ *
+ * Ensures placeholder hostnames are consistent across the docs:
+ * - "your Sourcegraph instance" is always `sourcegraph.example.com`
+ * - code hosts and other services are `<service>.example.com`
+ *   (e.g. `github.example.com`, `gitlab.example.com`, `redis.example.com`),
+ *   never a fictional company domain like `*.mycompany.com` or `*.acme.com`
+ * - internal Sourcegraph infrastructure (`*.sgdev.org`) never appears in docs
+ *
+ * Auto-generated SCHEMA_SYNC blocks are skipped: their text comes from the
+ * JSON schemas in sourcegraph/sourcegraph and must be fixed upstream.
+ * The technical changelog is skipped as a historical record.
+ *
+ * Runs as a GitHub Actions PR check (.github/workflows/check-hostnames.yml)
+ * and locally via `pnpm run check-hostnames`. No dependencies required.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import {fileURLToPath} from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const DOCS_DIR = path.join(path.dirname(__dirname), 'docs');
+
+const SOURCEGRAPH_HOST = 'sourcegraph.example.com';
+
+const SKIP_FILES = new Set(['technical-changelog.mdx']);
+
+const SCHEMA_SYNC_START = 'SCHEMA_SYNC_START';
+const SCHEMA_SYNC_END = 'SCHEMA_SYNC_END';
+
+/**
+ * Each rule is a regex for a disallowed hostname and a function producing
+ * the replacement to suggest for a given match.
+ */
+const RULES = [
+	// your-sourcegraph-instance.com, my_sourcegraph.io, ...
+	{
+		pattern:
+			/\b(?:your|my|our)[-_]?sourcegraph[-_a-z0-9]*\.(?:com|io|net|org|dev)\b/gi,
+		suggest: () => SOURCEGRAPH_HOST
+	},
+	// sourcegraph.yourcompany.com, sourcegraph.your-domain.com, sourcegraph.mycompany.com, ...
+	{
+		pattern:
+			/\bsourcegraph\.(?:your|my|our)[-_a-z0-9]*\.(?:com|io|net|org|dev)\b/gi,
+		suggest: () => SOURCEGRAPH_HOST
+	},
+	// sourcegraph.company.com, sourcegraph.acme.io, sourcegraph.test, sourcegraph.corp
+	{
+		pattern:
+			/\bsourcegraph\.(?:company|acme|corp|test)\b(?:\.(?:com|io|net|org|dev)\b)?(?::\d+)?/gi,
+		suggest: () => SOURCEGRAPH_HOST
+	},
+	// myinstance.sourcegraph.com, yourinstance.sourcegraph.com, example.sourcegraph.com, ...
+	{
+		pattern:
+			/\b(?:my|your)[-_]?(?:instance|domain|company)\.sourcegraph\.com\b|\bexample\.sourcegraph\.com\b/gi,
+		suggest: () => SOURCEGRAPH_HOST
+	},
+	// src.example.com, src.acme.com
+	{
+		pattern:
+			/\bsrc\.(?:example|acme|company|mycompany|yourcompany)\.com\b/gi,
+		suggest: () => SOURCEGRAPH_HOST
+	},
+	// my-gitlab.example.com -> gitlab.example.com
+	{
+		pattern: /\bmy-([a-z0-9]+)\.example\.com\b/gi,
+		suggest: m => m.replace(/^my-/i, '')
+	},
+	// Non-canonical spellings of common code hosts
+	{
+		pattern:
+			/\b(?:bitbucketserver|bitbucket-server|your-bbs-instance)\.example\.com\b/gi,
+		suggest: () => 'bitbucket.example.com'
+	},
+	{
+		pattern: /\b(?:github-enterprise|ghe)\.example\.com\b/gi,
+		suggest: () => 'github.example.com'
+	},
+	{
+		pattern: /\bsmtp-server\.example\.com\b/gi,
+		suggest: () => 'smtp.example.com'
+	},
+	// Any host under a fictional company domain -> *.example.com
+	// e.g. grafana.mycompany.com, psql1.mycompany.org, github.internal.company.net, artifactory.acme.com
+	{
+		pattern:
+			/\b(?:[a-z0-9-]+\.)+(?:mycompany|yourcompany|ourcompany|company|mycorp|corp|acme|mydomain|yourdomain)\.(?:com|net|io|org)\b/gi,
+		suggest: m =>
+			m.replace(/\.[a-z]+\.(?:com|net|io|org)$/i, '.example.com')
+	},
+	// Tenant placeholders on real SaaS domains: mycompany.onelogin.com -> example.onelogin.com
+	{
+		pattern:
+			/\b(?:mycompany|yourcompany|ourcompany|company|acme|myorg|yourorg)\.([a-z0-9-]+\.(?:com|net|io|org))\b/gi,
+		suggest: m => m.replace(/^[a-z]+\./i, 'example.')
+	},
+	// Internal Sourcegraph infrastructure must not leak into public docs
+	{
+		pattern: /\b[a-z0-9-]+(?:\.[a-z0-9-]+)*\.sgdev\.org\b/gi,
+		suggest: () => `${SOURCEGRAPH_HOST} (or <service>.example.com)`
+	}
+];
+
+async function main() {
+	console.log(
+		'🔍 Checking for non-canonical example hostnames in MDX files...\n'
+	);
+
+	const files = fs
+		.readdirSync(DOCS_DIR, {recursive: true})
+		.filter(f => f.endsWith('.mdx'))
+		.map(f => f.split(path.sep).join('/'));
+	const errors = [];
+
+	for (const file of files.sort()) {
+		if (SKIP_FILES.has(file)) continue;
+
+		const content = fs.readFileSync(path.join(DOCS_DIR, file), 'utf-8');
+		const lines = content.split('\n');
+		let inSchemaBlock = false;
+
+		for (let i = 0; i < lines.length; i++) {
+			const line = lines[i];
+			if (line.includes(SCHEMA_SYNC_START)) inSchemaBlock = true;
+			if (line.includes(SCHEMA_SYNC_END)) inSchemaBlock = false;
+			if (inSchemaBlock) continue;
+
+			for (const {pattern, suggest} of RULES) {
+				for (const match of line.matchAll(pattern)) {
+					errors.push({
+						file,
+						line: i + 1,
+						found: match[0],
+						suggestion: suggest(match[0])
+					});
+				}
+			}
+		}
+	}
+
+	if (errors.length === 0) {
+		console.log('✅ All example hostnames are canonical!');
+		process.exit(0);
+	}
+
+	console.log(
+		`❌ Found ${errors.length} non-canonical example hostname(s):\n`
+	);
+
+	for (const {file, line, found, suggestion} of errors) {
+		console.log(`   docs/${file}:${line}`);
+		console.log(`      found:   ${found}`);
+		console.log(`      use:     ${suggestion}\n`);
+	}
+
+	console.log(
+		`   Use \`${SOURCEGRAPH_HOST}\` for the Sourcegraph instance and \`<service>.example.com\`\n` +
+			'   (e.g. github.example.com, gitlab.example.com, bitbucket.example.com) for other hosts.\n'
+	);
+	process.exit(1);
+}
+
+main().catch(err => {
+	console.error('Error running hostname checker:', err);
+	process.exit(1);
+});

docs/admin/auth/saml/one-login.mdx

@@ -2,7 +2,7 @@
 
 ## 1. Create a SAML app in OneLogin
 
-1. Go to https://mycompany.onelogin.com/apps/find (replace "mycompany" with your company's OneLogin
+1. Go to https://example.onelogin.com/apps/find (replace "example" with your company's OneLogin
    ID).
 1. Type "saml" in the search field and select `SAML Custom Connector (Advanced)`, which uses the SAML 2.0 version. Click "Save".
 1. Under the "Configuration" tab, set the following properties (replacing `https://sourcegraph.example.com` with your Sourcegraph URL):
@@ -17,7 +17,7 @@
     -   - login: AD user name Include in SAML Assertion: ✓
 1. Save the app in OneLogin.
 1. Find the Issuer URL in the OneLogin app configuration page, under the "SSO" tab, under "Issuer
-   URL". It should look something like `https://mycompany.onelogin.com/saml/metadata/123456` or
+   URL". It should look something like `https://example.onelogin.com/saml/metadata/123456` or
    `https://app.onelogin.com/saml/metadata/123456`. Record this for the next section.
 
 ## 2. Add the SAML auth provider to Sourcegraph site config

docs/admin/code-hosts/bitbucket-server.mdx

@@ -81,7 +81,7 @@ Once a user has connected their Bitbucket Server account, either by signing-in v
 
 This section walks you through the process of setting up an _Application Link between Sourcegraph and Bitbucket Server / Bitbucket Data Center_ and configuring the Sourcegraph Bitbucket Server / Bitbucket Data Center configuration with `authorization` settings. It assumes the above prerequisites are met.
 
-As an admin user, go to the "Application Links" page. You can use the sidebar navigation in the admin dashboard, or go directly to [https://bitbucketserver.example.com/plugins/servlet/applinks/listApplicationLinks](https://bitbucketserver.example.com/plugins/servlet/applinks/listApplicationLinks).
+As an admin user, go to the "Application Links" page. You can use the sidebar navigation in the admin dashboard, or go directly to [https://bitbucket.example.com/plugins/servlet/applinks/listApplicationLinks](https://bitbucket.example.com/plugins/servlet/applinks/listApplicationLinks).
 
 > NOTE: There has been some [changes to the flow in Bitbucket v7.20](https://confluence.atlassian.com/bitbucketserver/bitbucket-data-center-and-server-7-20-release-notes-1101934428.html). Depending on your Bitbucket version, the setup is slightly different. Please follow the instructions for the correct version of Bitbucket below:
 

docs/admin/code-hosts/github.mdx

@@ -139,7 +139,7 @@ To add an existing GitHub App:
 1. Go to **Site admin > Repositories > Github Apps** on Sourcegraph.
 2. Click **Add an existing GitHub App**.
 3. Enter the following details of your existing GitHub App:
-    - **GitHub URL**: The URL of your GitHub instance (e.g., `https://github.com` or `https://github-enterprise.example.com`)
+    - **GitHub URL**: The URL of your GitHub instance (e.g., `https://github.com` or `https://github.example.com`)
     - **Client ID**: The unique identifier for your GitHub App
     - **Private Key**: The private key generated for your GitHub App (in PEM format)
 4. Click **Add GitHub App** to save the configuration.

docs/admin/code-hosts/gitlab.mdx

@@ -340,7 +340,7 @@ The Sourcegraph instance's site admin must [update the `corsOrigin` site config
 ```json
 {
 	// ...
-	"corsOrigin": "https://my-gitlab.example.com"
+	"corsOrigin": "https://gitlab.example.com"
 	// ...
 }
 ```

docs/admin/code-hosts/phabricator.mdx

@@ -63,7 +63,7 @@ The Sourcegraph instance's site admin must [update the `corsOrigin` site config
 ```json
 {
 	// ...
-	"corsOrigin": "https://my-phabricator.example.com"
+	"corsOrigin": "https://phabricator.example.com"
 	// ...
 }
 ```

docs/admin/config/authorization-and-authentication.mdx

@@ -9,7 +9,7 @@ We suggest configuring both when using Sourcegraph Enterprise. If you do not con
 
 ## Authentication
 
-Sourcegraph supports username/password auth by default and SAML, OAuth, HTTP Proxy auth, and OpenID Connect if configured. Changing a username in Sourcegraph will allow the user to escalate permissions, so if you are syncing permissions, you will need to add the following to your site config at `https://sourcegraph.yourdomain.com/siteadmin/configuration` ([Learn more about viewing and editing your site configuration.](/admin/config/site-config#view-and-edit-site-configuration))
+Sourcegraph supports username/password auth by default and SAML, OAuth, HTTP Proxy auth, and OpenID Connect if configured. Changing a username in Sourcegraph will allow the user to escalate permissions, so if you are syncing permissions, you will need to add the following to your site config at `https://sourcegraph.example.com/siteadmin/configuration` ([Learn more about viewing and editing your site configuration.](/admin/config/site-config#view-and-edit-site-configuration))
 
 ```json
 {
@@ -124,7 +124,7 @@ We support authentication through OAuth for [Azure DevOps Services (dev.azure.co
 
 1. In the `Name` field pick a descriptive name for this connection
 2. For `Supported account types` select `Accounts in this organizational directory only`
-3. For `Redirect URI` pick `Web`(!) for the type and set the URL field to `https://<myinstance.sourcegraph.com>/.auth/azuredevops/callback` if your Sourcegraph instance URL is https://myinstance.sourcegraph.com
+3. For `Redirect URI` pick `Web`(!) for the type and set the URL field to `https://sourcegraph.example.com/.auth/azuredevops/callback` if your Sourcegraph instance URL is https://sourcegraph.example.com
 4. Click **Register**
 5. Now go to the [Microsoft Entra admin center](https://entra.microsoft.com/) as at least an **Application Developer**.
 6. Go to **App registrations** and select the one you just created.

docs/admin/how-to/converting-version-contexts-to-search-contexts.mdx

@@ -22,10 +22,10 @@ Reload after saving changes to see search contexts enabled.
 ## Steps to convert version contexts to search contexts
 
 1. Log in to your private Sourcegraph instance as a site admin.
-2. Navigate to `https://your_sourcegraph_instance.com/contexts`.
+2. Navigate to `https://sourcegraph.example.com/contexts`.
 3. Press `Convert version contexts`. A list of [existing version contexts](/code-search/features#version-contexts-sunsetting) found in the site configuration will be shown.
 4. Convert either all version contexts at once, or specific individual version contexts as desired.
-5. Navigate back to `https://your_sourcegraph_instance.com/contexts`. Converted version contexts will be listed.
+5. Navigate back to `https://sourcegraph.example.com/contexts`. Converted version contexts will be listed.
 
 Converted search contexts can be used immediately by users on the Sourcegraph instance. The contexts selector will be shown in the search input.
 

docs/admin/how-to/internal-github-repos.mdx

@@ -25,7 +25,7 @@ For example:
 
 ### How to check that you now have internal repositories
 
-Confirm that you have cloned repositories in your instance by accessing your GraphQL console on `$your_sourcegraph_url/api/console` and running the following query;
+Confirm that you have cloned repositories in your instance by accessing your GraphQL console on `https://sourcegraph.example.com/api/console` and running the following query;
 
 ```
 query{

docs/admin/how-to/manage-feature-flags-with-graphql.mdx

@@ -8,7 +8,7 @@ Some Sourcegraph instances do not expose the feature flag admin UI. In those cas
 -   Sign in to your instance:
 
 ```bash
-src login https://your-sourcegraph-instance.com
+src login https://sourcegraph.example.com
 ```
 
 ## List all feature flags

docs/admin/how-to/unknown-error-login.mdx

@@ -15,8 +15,8 @@ This document will attempt to identify a common reason for an `Unknown Error` wh
 
 2. This is often a result of an `http/https` protocol mismatch between what is in the site configuration for `externalURL`, and what the user is trying to log in to
 
-    - For example, if the protocol in the site configuration is set to `https://sourcegraph.your_instance_name.com`
-    - And the user is trying to login at the `http://sourcegraph.your_instance_name.com`, then this error can be displayed
+    - For example, if the protocol in the site configuration is set to `https://sourcegraph.example.com`
+    - And the user is trying to login at the `http://sourcegraph.example.com`, then this error can be displayed
 
 ### Things to check
 

docs/admin/scim.mdx

@@ -65,7 +65,7 @@ To configure:
 4. Set up your IdP to use our SCIM API. The API is at
 
     ```
-    https://sourcegraph.company.com/.api/scim/v2/
+    https://sourcegraph.example.com/.api/scim/v2/
     ```
 
 ## Configuring SCIM for Okta

docs/api/mcp/authentication.mdx

@@ -53,7 +53,7 @@ If it does not, use [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) as
 		"command": "npx",
 		"args": [
 			"mcp-remote",
-			"https://your-sourcegraph-instance.com/.api/mcp",
+			"https://sourcegraph.example.com/.api/mcp",
 			"3334",
 			"--static-oauth-client-info",
 			"{\"client_id\":\"YOUR_CLIENT_ID\"}",
@@ -64,7 +64,7 @@ If it does not, use [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) as
 }
 ```
 
-Replace `your-sourcegraph-instance.com` with your Sourcegraph instance URL and `YOUR_CLIENT_ID` with the client ID you copied. Start the MCP client and complete authorization in your browser.
+Replace `sourcegraph.example.com` with your Sourcegraph instance URL and `YOUR_CLIENT_ID` with the client ID you copied. Start the MCP client and complete authorization in your browser.
 
 ## Disable Dynamic Client Registration