From c97d50caab4b8d0fc3495854c3d9e996ff39db2c Mon Sep 17 00:00:00 2001
From: Warren Gifford <warrenbruceg@gmail.com>
Date: Wed, 25 Jun 2025 20:08:08 -0700
Subject: [PATCH 1/2] copy the tribal knowledge contained in the config files
 to a section beneath the actual config

---
 docs/admin/code_hosts/aws_codecommit.mdx   | 125 +++++++++++++++
 docs/admin/code_hosts/azuredevops.mdx      | 105 ++++++++++++
 docs/admin/code_hosts/bitbucket_cloud.mdx  | 159 ++++++++++++++++++
 docs/admin/code_hosts/bitbucket_server.mdx | 178 +++++++++++++++++++++
 docs/admin/code_hosts/gerrit.mdx           | 134 ++++++++++++++++
 docs/admin/code_hosts/github.mdx           | 159 ++++++++++++++++++
 docs/admin/code_hosts/gitlab.mdx           | 171 ++++++++++++++++++++
 docs/admin/code_hosts/gitolite.mdx         |  53 ++++++
 docs/admin/code_hosts/other.mdx            |  80 +++++++++
 docs/admin/code_hosts/phabricator.mdx      |  56 +++++++
 docs/admin/config/settings.mdx             | 166 +++++++++++++++++++
 docs/admin/config/site_config.mdx          | 175 ++++++++++++++++++++
 docs/admin/repo/perforce.mdx               |  80 +++++++++
 13 files changed, 1641 insertions(+)

diff --git a/docs/admin/code_hosts/aws_codecommit.mdx b/docs/admin/code_hosts/aws_codecommit.mdx
index 8fb8fcac8..2d9cebdac 100644
--- a/docs/admin/code_hosts/aws_codecommit.mdx
+++ b/docs/admin/code_hosts/aws_codecommit.mdx
@@ -114,6 +114,131 @@ To add CodeCommit repositories in Docker Container:
 ```
 {/* SCHEMA_SYNC_END: admin/code_hosts/aws_codecommit.schema.json */}
 
+## Configuration Notes
+
+### Git Credentials Requirement
+AWS CodeCommit **requires** Git credentials for HTTPS authentication since Sourcegraph version 3.4:
+- Git credentials consist of a username and password generated in AWS IAM
+- These are different from your regular AWS access keys
+- Follow the [AWS Git credentials setup guide](https://docs.aws.amazon.com/codecommit/latest/userguide/setting-up-gc.html) for detailed instructions
+
+### Repository Path Patterns
+The `repositoryPathPattern` field allows customization of repository URLs within Sourcegraph:
+- Default pattern: `"{name}"` results in URLs like `src.example.com/myrepo`
+- Region-specific pattern: `"git-codecommit.us-west-1.amazonaws.com/{name}"` for better organization
+- Ensure patterns generate unique repository names to avoid conflicts
+
+### Authentication Methods
+AWS CodeCommit supports both HTTPS and SSH authentication:
+- **HTTPS**: Uses Git credentials (username/password) - recommended for simplicity
+- **SSH**: Uses SSH key pairs - requires additional key management setup
+
+## Security Considerations
+
+### IAM Permissions
+- The AWS access key must have the **AWSCodeCommitReadOnly** IAM policy attached minimum
+- Consider using more restrictive custom policies that limit access to specific repositories
+- Never use root account credentials - create dedicated IAM users for Sourcegraph
+
+### Credential Storage
+- Store AWS access keys and secrets securely using Sourcegraph's secret management
+- For SSH setups, ensure private keys are base64 encoded and properly secured
+- Regularly rotate AWS access keys according to security best practices
+
+### Network Access
+- Ensure Sourcegraph can reach AWS CodeCommit endpoints in your configured region
+- Consider VPC endpoints for private network access to CodeCommit
+- Review AWS CloudTrail logs for monitoring repository access
+
+### SSH Key Security
+- Generate SSH keys without passphrases for automated access
+- Store private keys securely and base64 encode them for configuration
+- Regularly rotate SSH keys and update configurations accordingly
+
+## Common Examples
+
+### Basic HTTPS Configuration
+```json
+{
+  "accessKeyID": "AKIA...",
+  "secretAccessKey": "your-secret-key", 
+  "region": "us-east-1",
+  "gitCredentials": {
+    "username": "git-username",
+    "password": "git-password"
+  },
+  "repositoryPathPattern": "{name}"
+}
+```
+
+### Region-Specific Setup
+```json
+{
+  "accessKeyID": "AKIA...",
+  "secretAccessKey": "your-secret-key",
+  "region": "eu-central-1", 
+  "gitCredentials": {
+    "username": "git-username",
+    "password": "git-password"
+  },
+  "repositoryPathPattern": "git-codecommit.eu-central-1.amazonaws.com/{name}"
+}
+```
+
+### SSH Configuration
+```json
+{
+  "accessKeyID": "AKIA...",
+  "secretAccessKey": "your-secret-key",
+  "region": "us-west-1",
+  "gitURLType": "ssh",
+  "gitSSHKeyID": "APKA...",
+  "gitSSHCredential": {
+    "privateKey": "LS0tLS1CRUdJTi...",
+    "passphrase": ""
+  }
+}
+```
+
+### Selective Repository Sync
+```json
+{
+  "accessKeyID": "AKIA...",
+  "secretAccessKey": "your-secret-key",
+  "region": "us-east-1",
+  "gitCredentials": {
+    "username": "git-username", 
+    "password": "git-password"
+  },
+  "exclude": [
+    {"name": "internal-temp-repo"},
+    {"name": "archived-project"}
+  ]
+}
+```
+
+## Best Practices
+
+### Performance and Reliability
+- **Regional Deployment**: Deploy Sourcegraph in the same AWS region as your CodeCommit repositories for optimal performance
+- **Repository Exclusion**: Use the `exclude` field to avoid syncing temporary or archived repositories
+- **Connection Monitoring**: Regularly verify that your AWS credentials remain valid and have appropriate permissions
+
+### Operational Management
+- **Credential Rotation**: Implement regular rotation of AWS access keys and Git credentials
+- **Monitoring**: Set up CloudWatch alarms for CodeCommit API usage and authentication failures
+- **Backup Strategy**: Ensure your repository syncing strategy aligns with your backup and disaster recovery plans
+
+### Deployment Considerations
+- **Docker Deployments**: For SSH setups, properly mount SSH configuration files into containers
+- **Kubernetes Deployments**: Use secrets for credential management and configure SSH access appropriately
+- **Container Restart**: Plan for service restarts when updating SSH keys or credentials
+
+### Migration and Setup
+- **Testing**: Always test your configuration with a small subset of repositories first
+- **Documentation**: Document your repository path patterns and credential management processes
+- **Access Validation**: Verify Sourcegraph can access all intended repositories before full deployment
+
 ### Mounting SSH keys into the container
 
 1. Copy all the files at your `$HOME/.ssh directory` to `$HOME/.sourcegraph/config/ssh` directory. See [docs](/admin/deploy/docker-single-container/#ssh-authentication-config-keys-knownhosts) for more information about our ssh file system.
diff --git a/docs/admin/code_hosts/azuredevops.mdx b/docs/admin/code_hosts/azuredevops.mdx
index 526a6b22f..fd23d7f17 100644
--- a/docs/admin/code_hosts/azuredevops.mdx
+++ b/docs/admin/code_hosts/azuredevops.mdx
@@ -129,6 +129,111 @@ Azure DevOps connections support the following configuration options, which are
 ```
 {/* SCHEMA_SYNC_END: admin/code_hosts/azuredevops.schema.json */}
 
+## Configuration Notes
+
+### Token Requirements
+- Personal Access Token must have **All accessible organizations** scope to support connection checks and multi-organization syncing
+- Required scopes: Code (Read), Project and Team, User Profile
+- Consider creating a dedicated service account with minimal required permissions for production deployments
+
+### Organization Access
+Azure DevOps connections support both organization-level and project-level syncing:
+- Use `"orgs": ["org1", "org2"]` to sync all repositories from specific organizations
+- Use `"projects": ["org1/project1", "org2/project2"]` for granular project-level control
+- Both options can be combined in a single configuration
+
+### Repository Exclusion
+The `exclude` configuration supports both exact name matching and pattern-based exclusion:
+- Exact match: `{"name": "myorg/myproject/myrepo"}`
+- Pattern match: `{"pattern": "^topsecretproject/.*"}`
+
+## Security Considerations
+
+### Access Control
+- **Permissions Enforcement**: Set `"enforcePermissions": true` to sync user-level access controls from Azure DevOps
+- **OAuth Configuration**: Required for permission syncing - users must authenticate with Azure DevOps OAuth
+- **Third-party OAuth**: Must be enabled in Azure DevOps organization settings under Security → Policies
+
+### Credential Management
+- Store Personal Access Tokens securely using Sourcegraph's secret management
+- Regularly rotate tokens according to your organization's security policies
+- Use dedicated service accounts rather than personal user accounts for production
+
+### Network Security
+- Ensure HTTPS-only communication by using `"gitURLType": "http"` with HTTPS URLs
+- For SSH access, properly manage SSH keys and known_hosts configuration
+- Configure firewall rules to allow Sourcegraph access to Azure DevOPS endpoints
+
+## Common Examples
+
+### Basic Organization Sync
+```json
+{
+  "url": "https://dev.azure.com/",
+  "username": "service-account",
+  "token": "your-personal-access-token",
+  "orgs": ["your-organization"],
+  "gitURLType": "http"
+}
+```
+
+### Multi-Project Configuration
+```json
+{
+  "url": "https://dev.azure.com/",
+  "username": "service-account", 
+  "token": "your-personal-access-token",
+  "projects": [
+    "org1/frontend-project",
+    "org1/backend-project",
+    "org2/shared-libraries"
+  ],
+  "exclude": [
+    {"name": "org1/legacy-project"},
+    {"pattern": "^.*/archived-.*"}
+  ]
+}
+```
+
+### SSH Configuration
+```json
+{
+  "url": "https://dev.azure.com/",
+  "username": "service-account",
+  "token": "your-personal-access-token",
+  "orgs": ["your-organization"],
+  "gitURLType": "ssh"
+}
+```
+
+### Permissions-Enabled Setup
+```json
+{
+  "url": "https://dev.azure.com/",
+  "username": "service-account",
+  "token": "your-personal-access-token",
+  "orgs": ["your-organization"],
+  "enforcePermissions": true
+}
+```
+
+## Best Practices
+
+### Performance Optimization
+- **Selective Syncing**: Use `projects` instead of `orgs` when you only need specific repositories
+- **Exclude Patterns**: Use exclusion patterns to avoid syncing unnecessary repositories like archived projects
+- **Rate Limit Awareness**: Sourcegraph automatically handles Azure DevOps rate limits, but consider the impact on large organizations
+
+### Maintenance
+- **Regular Token Rotation**: Implement a process for rotating Personal Access Tokens
+- **Monitor Sync Status**: Regularly check repository sync status in the Site Admin interface
+- **Permission Sync Monitoring**: For permission-enabled setups, monitor user permission sync completion
+
+### Troubleshooting
+- **Connection Issues**: Verify token permissions and organization access settings
+- **Missing Repositories**: Check exclude patterns and ensure the token has access to all target organizations/projects  
+- **Permission Problems**: Verify OAuth is properly configured and Third-party application access is enabled
+
 ## Webhooks
 
 Please consult [this page](/admin/config/webhooks/incoming) in order to configure webhooks.
diff --git a/docs/admin/code_hosts/bitbucket_cloud.mdx b/docs/admin/code_hosts/bitbucket_cloud.mdx
index bea39f980..246d4d85f 100644
--- a/docs/admin/code_hosts/bitbucket_cloud.mdx
+++ b/docs/admin/code_hosts/bitbucket_cloud.mdx
@@ -208,6 +208,165 @@ Bitbucket Cloud connections support the following configuration options, which a
 ```
 {/* SCHEMA_SYNC_END: admin/code_hosts/bitbucket_cloud.schema.json */}
 
+## Configuration Notes
+
+Bitbucket Cloud connections provide streamlined configuration for cloud-hosted repositories:
+
+- **Authentication Options**: Support for both username/app password and workspace access tokens
+- **Repository Selection**: Uses `teams` for workspace-based syncing and `exclude` for filtering unwanted repositories
+- **Path Patterns**: The `repositoryPathPattern` field uses `{host}` and `{nameWithOwner}` variables for repository naming
+- **Workspace Access**: Workspace access tokens provide more granular control than user-based app passwords
+
+### Authentication Methods
+
+Bitbucket Cloud supports two primary authentication approaches:
+- **Username/App Password**: User-scoped access with app passwords created in personal settings
+- **Workspace Access Token**: Workspace-scoped access tokens with fine-grained permissions
+- **Projects/Repositories Permissions**: Both methods require `Projects: Read` and `Repositories: Read` permissions
+
+### Rate Limiting Configuration
+
+Bitbucket Cloud connections include rate limiting for API management:
+- Default: 7,200 requests per hour with rate limiting enabled
+- Bitbucket Cloud enforces [API request limits](https://support.atlassian.com/bitbucket-cloud/docs/api-request-limits/) based on plan type
+- Sourcegraph implements exponential backoff for rate limit handling
+
+## Security Considerations
+
+### Authentication Security
+
+**App Passwords**: Provide user-level access with specific permissions:
+- Create app passwords with minimal required permissions (`Projects: Read`, `Repositories: Read`)
+- Use dedicated service accounts rather than personal accounts when possible
+- App passwords inherit the user's repository access permissions
+- Regularly audit and rotate app passwords
+
+**Workspace Access Tokens**: Provide workspace-level access control:
+- More secure than user-based app passwords for organizational use
+- Scoped to specific workspaces, limiting access surface
+- Support fine-grained permissions for better security posture
+- Recommended for production deployments
+
+### Repository Permissions
+
+Bitbucket Cloud permission syncing considerations:
+- Permission syncing requires Bitbucket Cloud as an authentication provider
+- User access is determined by their Bitbucket Cloud account permissions
+- Workspace access tokens provide read-only access to repositories
+- OAuth flow ensures proper user authentication and authorization
+
+### HTTPS Security
+
+Bitbucket Cloud connections use HTTPS by default:
+- All API communication is encrypted using TLS
+- Git operations use HTTPS with authentication credentials
+- SSH access is supported but requires additional key configuration
+- No custom certificate configuration needed for cloud service
+
+## Common Examples
+
+### Basic Team Sync with App Password
+```json
+{
+  "url": "https://bitbucket.org",
+  "username": "sourcegraph-bot",
+  "appPassword": "ATBBxxxxxxxxxxxxxxxxxx",
+  "teams": [
+    "engineering-team",
+    "platform-team"
+  ]
+}
+```
+
+### Workspace Access Token Configuration
+```json
+{
+  "url": "https://bitbucket.org",
+  "accessToken": "BBAR-xxxxxxxxxxxxxxxxxx",
+  "teams": ["my-workspace"],
+  "exclude": [
+    {"name": "my-workspace/legacy-project"},
+    {"pattern": "^.*-archive$"}
+  ]
+}
+```
+
+### SSH Access with Custom Path Pattern
+```json
+{
+  "url": "https://bitbucket.org",
+  "username": "deployment-user",
+  "appPassword": "ATBBxxxxxxxxxxxxxxxxxx",
+  "teams": ["mobile-apps"],
+  "gitURLType": "ssh",
+  "repositoryPathPattern": "bitbucket/{nameWithOwner}"
+}
+```
+
+### Repository Permissions with OAuth
+```json
+{
+  "url": "https://bitbucket.org",
+  "accessToken": "BBAR-xxxxxxxxxxxxxxxxxx",
+  "teams": ["enterprise-workspace"],
+  "authorization": {},
+  "exclude": [
+    {"name": "enterprise-workspace/internal-docs"}
+  ]
+}
+```
+
+### High-volume Configuration with Rate Limiting
+```json
+{
+  "url": "https://bitbucket.org",
+  "accessToken": "BBAR-xxxxxxxxxxxxxxxxxx", 
+  "teams": ["large-organization"],
+  "rateLimit": {
+    "enabled": true,
+    "requestsPerHour": 5000
+  },
+  "webhookSecret": "your-webhook-secret-here"
+}
+```
+
+## Best Practices
+
+### Authentication Management
+
+1. **Use workspace access tokens** for production deployments instead of personal app passwords
+2. **Create dedicated service accounts** when using username/app password authentication
+3. **Apply least-privilege principles** by granting only necessary permissions
+4. **Regularly audit token usage** and rotate credentials periodically
+
+### Repository Organization
+
+1. **Organize by workspaces** using the `teams` field to sync relevant repositories
+2. **Use exclusion patterns** to filter out archived, experimental, or sensitive repositories
+3. **Implement consistent naming** with `repositoryPathPattern` for better organization
+4. **Monitor workspace changes** as team membership affects repository access
+
+### Performance Optimization
+
+1. **Configure appropriate rate limits** to stay within Bitbucket Cloud's API limits
+2. **Use workspace access tokens** for better rate limit handling
+3. **Monitor API usage** to avoid hitting plan-based limits
+4. **Optimize team selections** to sync only necessary repositories
+
+### Security Management
+
+1. **Enable repository permissions** by configuring Bitbucket Cloud as an auth provider
+2. **Use workspace access tokens** for better security isolation
+3. **Implement webhook security** with strong shared secrets
+4. **Regularly review team membership** to ensure appropriate repository access
+
+### Maintenance
+
+1. **Monitor connection health** through the site admin interface
+2. **Review team configurations** as organizational structure changes
+3. **Update exclusion patterns** when repository naming conventions change
+4. **Test authentication changes** in staging environments before production deployment
+
 ## Webhooks
 
 Using the `webhooks` property on the external service has been deprecated.
diff --git a/docs/admin/code_hosts/bitbucket_server.mdx b/docs/admin/code_hosts/bitbucket_server.mdx
index ae64c6486..0735d6e6b 100644
--- a/docs/admin/code_hosts/bitbucket_server.mdx
+++ b/docs/admin/code_hosts/bitbucket_server.mdx
@@ -331,3 +331,181 @@ Bitbucket Server / Bitbucket Data Center connections support the following confi
 }
 ```
 {/* SCHEMA_SYNC_END: admin/code_hosts/bitbucket_server.schema.json */}
+
+## Configuration Notes
+
+Bitbucket Server/Data Center connections provide comprehensive configuration options for enterprise environments:
+
+- **Repository Selection**: Use `repos` for specific repositories in `projectKey/repositorySlug` format, `repositoryQuery` for API-based filtering, and `exclude` for fine-grained exclusions
+- **Project Keys**: The `projectKeys` field allows syncing all repositories from specific projects
+- **Personal Repository Handling**: Use `excludePersonalRepositories` to filter out personal repositories that may be accessible
+- **Path Patterns**: The `repositoryPathPattern` field supports variables like `{host}`, `{projectKey}`, and `{repositorySlug}` for flexible repository naming
+
+### Authentication Methods
+
+Bitbucket Server supports multiple authentication approaches:
+- **Personal Access Tokens**: Recommended for v5.5+ with granular permissions
+- **Username/Password**: Required for older versions (pre-5.5) that don't support PATs
+- **OAuth1**: For permission syncing with application links
+- **OAuth2**: Simplified permission syncing (requires auth provider configuration)
+
+### Rate Limiting Configuration
+
+Bitbucket Server connections include rate limiting for API management:
+- Default: 28,800 requests per hour with rate limiting enabled
+- Adjust based on your instance's capacity and usage patterns
+- Monitor API usage to prevent hitting Bitbucket's internal limits
+
+## Security Considerations
+
+### Authentication Security
+
+**Personal Access Tokens**: Provide fine-grained access control:
+- Create tokens with minimal required permissions (read for syncing, write for Batch Changes)
+- Use dedicated service accounts rather than personal tokens
+- Regularly rotate tokens and audit their usage
+- Tokens are preferred over username/password for better security
+
+**OAuth Configuration**: Requires careful setup but provides enhanced security:
+- OAuth1 requires RSA key pairs and proper application link configuration
+- OAuth2 provides simpler setup with similar security benefits
+- Both methods support user impersonation for proper permission syncing
+
+### Permission Syncing Security
+
+Bitbucket Server permission syncing has specific security requirements:
+- **Username Matching**: Requires identical usernames between Sourcegraph and Bitbucket Server
+- **External Authentication**: Use LDAP/Active Directory for consistent user management
+- **Username Changes**: Disable username changes (`auth.enableUsernameChanges: false`) to prevent privilege escalation
+- **Plugin Benefits**: The Sourcegraph plugin enables more efficient permission syncing and personal repository support
+
+### SSL/TLS Configuration
+
+For Bitbucket Server instances with custom certificates:
+- Use the `certificate` field to specify custom CA certificates
+- Obtain certificates using: `openssl s_client -connect HOST:443 -showcerts`
+- Ensure certificate chain includes all intermediate certificates
+
+### Application Link Security
+
+When configuring OAuth1 application links:
+- Generate strong consumer keys using cryptographic randomness
+- Use RSA keys with at least 4096-bit length
+- Store private keys securely and restrict access
+- Enable 2-Legged OAuth with proper execute-as user configuration
+
+## Common Examples
+
+### Basic Repository Sync with Personal Access Token
+```json
+{
+  "url": "https://bitbucket.company.com",
+  "username": "sourcegraph-service",
+  "token": "NjY4MDAzNDI2NTMx...",
+  "repos": [
+    "PROJECT/repository-name",
+    "SHARED/common-library"
+  ]
+}
+```
+
+### Project-wide Sync with Exclusions
+```json
+{
+  "url": "https://bitbucket.company.com",
+  "username": "sourcegraph-service", 
+  "token": "NjY4MDAzNDI2NTMx...",
+  "projectKeys": ["ENGINEERING", "PLATFORM"],
+  "exclude": [
+    {"name": "ENGINEERING/deprecated-service"},
+    {"pattern": "^.*-archive$"}
+  ],
+  "excludePersonalRepositories": true
+}
+```
+
+### Advanced Query with OAuth2 Authorization
+```json
+{
+  "url": "https://bitbucket.company.com",
+  "username": "sourcegraph-service",
+  "token": "NjY4MDAzNDI2NTMx...",
+  "repositoryQuery": [
+    "?name=microservice&projectname=PLATFORM",
+    "?visibility=public"
+  ],
+  "authorization": {
+    "oauth2": true
+  }
+}
+```
+
+### SSH Configuration with Custom Path Pattern
+```json
+{
+  "url": "https://bitbucket.company.com",
+  "username": "sourcegraph-service",
+  "token": "NjY4MDAzNDI2NTMx...",
+  "repositoryQuery": ["?projectname=MOBILE"],
+  "gitURLType": "ssh",
+  "repositoryPathPattern": "bitbucket/{projectKey}/{repositorySlug}",
+  "certificate": "-----BEGIN CERTIFICATE-----\n..."
+}
+```
+
+### Plugin-enabled Fast Permission Sync
+```json
+{
+  "url": "https://bitbucket.company.com", 
+  "username": "sourcegraph-service",
+  "token": "NjY4MDAzNDI2NTMx...",
+  "repositoryQuery": ["all"],
+  "authorization": {
+    "oauth2": true
+  },
+  "plugin": {
+    "permissions": "enabled"
+  },
+  "rateLimit": {
+    "enabled": true,
+    "requestsPerHour": 20000
+  }
+}
+```
+
+## Best Practices
+
+### Authentication Management
+
+1. **Use Personal Access Tokens** whenever possible instead of username/password authentication
+2. **Create dedicated service accounts** for Sourcegraph rather than using personal accounts
+3. **Implement token rotation** policies to regularly refresh access tokens
+4. **Configure OAuth2** for permission syncing when user authentication is required
+
+### Repository Organization
+
+1. **Use project-based organization** with `projectKeys` for better management at scale
+2. **Implement exclusion patterns** to filter out archived, personal, or test repositories
+3. **Use consistent path patterns** that reflect your organizational structure
+4. **Exclude personal repositories** unless specifically required for your use case
+
+### Performance Optimization
+
+1. **Install the Sourcegraph plugin** for faster permission syncing and enhanced features
+2. **Configure appropriate rate limits** based on your Bitbucket Server instance's capacity
+3. **Use specific repository queries** rather than broad "all" queries when possible
+4. **Monitor API usage** to avoid overloading your Bitbucket Server instance
+
+### Permission Management
+
+1. **Ensure username consistency** between Sourcegraph and Bitbucket Server through external auth
+2. **Disable username changes** in Sourcegraph site configuration to prevent privilege escalation
+3. **Test permission syncing** thoroughly before deploying to production
+4. **Use the Sourcegraph plugin** for more efficient permission syncing
+
+### Maintenance
+
+1. **Monitor connection health** through the site admin interface
+2. **Keep certificates updated** for Bitbucket Server instances with custom SSL
+3. **Review repository queries** periodically as your project structure evolves
+4. **Update the Sourcegraph plugin** when new versions become available
diff --git a/docs/admin/code_hosts/gerrit.mdx b/docs/admin/code_hosts/gerrit.mdx
index 17457d8bb..f468b5b66 100644
--- a/docs/admin/code_hosts/gerrit.mdx
+++ b/docs/admin/code_hosts/gerrit.mdx
@@ -154,3 +154,137 @@ Gerrit connections support the following configuration options, which are specif
 }
 ```
 {/* SCHEMA_SYNC_END: admin/code_hosts/gerrit.schema.json */}
+
+## Configuration Notes
+
+### HTTP Credentials Setup
+Gerrit requires HTTP credentials for API access and repository cloning:
+- Generate credentials in Gerrit web UI under Settings → HTTP Credentials
+- The configured user must have access to all repositories that need to be mirrored
+- HTTP credentials are separate from Gerrit user passwords
+
+### Project vs Repository Mirroring
+Gerrit organizes code in projects, not individual repositories:
+- Use `"projects": ["docs", "kubernetes/kubernetes"]` to specify which projects to mirror
+- If `projects` is empty or omitted, all projects on the Gerrit instance will be mirrored
+- Project names follow the format shown in Gerrit's project list
+
+### Authentication and Authorization
+The `authorization` field controls access to private repositories:
+- Include `"authorization": {}` to mark all repositories as private
+- Requires corresponding Gerrit authentication provider in site configuration
+- Users must authenticate with their Gerrit HTTP credentials to access repositories
+
+## Security Considerations
+
+### Access Control
+- **Private Repository Access**: Enable authorization to enforce Gerrit permissions in Sourcegraph
+- **Authentication Provider Required**: Configure Gerrit as an auth provider when using authorization
+- **User Permission Sync**: Sourcegraph respects Gerrit's project-level access controls
+
+### Credential Management
+- **Service Account**: Use a dedicated Gerrit account with appropriate permissions for mirroring
+- **HTTP Credentials**: Store HTTP username and password securely using Sourcegraph's secret management
+- **SSH Keys**: For SSH cloning, ensure private keys are base64 encoded and securely stored
+
+### Network Security
+- **HTTPS Communication**: Always use HTTPS URLs for Gerrit connections
+- **SSH Configuration**: If using SSH, properly manage SSH keys and known_hosts configuration
+- **Firewall Rules**: Ensure Sourcegraph can reach Gerrit endpoints on required ports
+
+### Permission Synchronization
+- **Real-time Sync**: User permissions may take time to synchronize from Gerrit
+- **Access Validation**: Users without proper Gerrit access will be denied repository access
+- **Project-Level Control**: Permissions are enforced at the Gerrit project level
+
+## Common Examples
+
+### Basic Public Repository Setup
+```json
+{
+  "url": "https://gerrit.example.com/",
+  "username": "sourcegraph-service",
+  "password": "http-credentials-password",
+  "projects": [
+    "public-docs",
+    "open-source-project"
+  ]
+}
+```
+
+### Private Repository with Authorization
+```json
+{
+  "url": "https://gerrit.example.com/",
+  "username": "sourcegraph-service", 
+  "password": "http-credentials-password",
+  "projects": [
+    "internal/backend",
+    "internal/frontend",
+    "shared/libraries"
+  ],
+  "authorization": {}
+}
+```
+
+### SSH-Based Cloning
+```json
+{
+  "url": "https://gerrit.example.com/",
+  "username": "sourcegraph-service",
+  "password": "http-credentials-password", 
+  "projects": [
+    "docs",
+    "kubernetes/kubernetes"
+  ],
+  "gitSSHCredential": {
+    "privateKey": "LS0tLS1CRUdJTi5CRUdJTiBPUE..."
+  },
+  "authorization": {}
+}
+```
+
+### Selective Project Exclusion
+```json
+{
+  "url": "https://gerrit.example.com/",
+  "username": "sourcegraph-service",
+  "password": "http-credentials-password",
+  "projects": [
+    "active-project-1",
+    "active-project-2", 
+    "legacy-project"
+  ],
+  "exclude": [
+    {"name": "legacy-project"}
+  ]
+}
+```
+
+## Best Practices
+
+### Setup and Configuration
+- **Service Account**: Create a dedicated Gerrit account for Sourcegraph with minimal required permissions
+- **Project Selection**: Be selective about which projects to mirror to avoid unnecessary resource usage
+- **URL Consistency**: Ensure the Gerrit URL in code host config matches the auth provider URL exactly
+
+### Authentication Management
+- **Auth Provider Setup**: Always configure Gerrit authentication provider when using authorization
+- **User Onboarding**: Educate users on how to connect their Gerrit accounts to Sourcegraph
+- **Permission Testing**: Test that users can access appropriate repositories after connecting accounts
+
+### Performance Optimization
+- **Selective Mirroring**: Use specific project lists rather than mirroring all projects
+- **Exclusion Patterns**: Use exclude rules to skip archived or inactive projects
+- **Connection Monitoring**: Monitor Gerrit API usage and response times
+
+### Operational Considerations
+- **Credential Rotation**: Implement regular rotation of HTTP credentials
+- **Permission Sync Monitoring**: Monitor user permission synchronization status
+- **Project Changes**: Update project lists when new projects are created or old ones archived
+
+### Troubleshooting
+- **Connection Issues**: Verify HTTP credentials and Gerrit instance accessibility
+- **Missing Projects**: Check project names match exactly as shown in Gerrit
+- **Permission Problems**: Ensure auth provider configuration matches code host URL
+- **User Access Issues**: Verify users have connected their Gerrit accounts and permissions have synced
diff --git a/docs/admin/code_hosts/github.mdx b/docs/admin/code_hosts/github.mdx
index 84cd878b7..ccc01a9d3 100644
--- a/docs/admin/code_hosts/github.mdx
+++ b/docs/admin/code_hosts/github.mdx
@@ -584,3 +584,162 @@ If you would like to sync all public repositories while omitting archived repos,
 }
 ```
 {/* SCHEMA_SYNC_END: admin/code_hosts/github.schema.json */}
+
+## Configuration Notes
+
+The GitHub connection schema provides several configuration patterns for different use cases:
+
+- **Repository Selection**: Use `repos` for specific repositories, `orgs` for all repositories in organizations, and `repositoryQuery` for advanced filtering with search queries
+- **Path Patterns**: The `repositoryPathPattern` field controls how repository names appear in Sourcegraph URLs - ensure patterns are unique across code hosts to avoid collisions
+- **Token Configuration**: The `token` field supports personal access tokens, fine-grained tokens, and machine user tokens depending on your access requirements
+
+### Rate Limiting Configuration
+
+The `rateLimit` configuration allows fine-tuning of API request rates:
+- Default: 5000 requests per hour with rate limiting enabled
+- Adjust `requestsPerHour` based on your GitHub instance's limits and usage patterns
+- Setting `enabled: false` disables rate limiting but may result in API errors
+
+### Repository Query Options
+
+The `repositoryQuery` field accepts several special values:
+- `public`: All public repositories (GitHub Enterprise only)
+- `affiliated`: Repositories the token user has access to
+- `internal`: Internal repositories (GitHub Enterprise only)  
+- `none`: No automatic repository discovery
+- Custom search queries: GitHub advanced search syntax for complex filtering
+
+## Security Considerations
+
+### Token Security and Scoping
+
+**Personal Access Tokens**: Grant broad access equivalent to the token owner's permissions. Consider these security practices:
+- Use dedicated service accounts rather than personal tokens when possible
+- Apply the principle of least privilege - only grant necessary scopes
+- Regularly rotate tokens and audit their usage
+
+**Fine-grained Access Tokens**: Provide repository-specific permissions but have limitations:
+- Only work with repositories owned by the token creator
+- Cannot access GitHub's GraphQL API (required for `repositoryQuery` and Batch Changes)
+- Limited to REST API functionality
+
+### Certificate Validation
+
+For GitHub Enterprise instances with self-signed certificates:
+- Use the `certificate` field to specify custom CA certificates
+- Obtain certificates using: `openssl s_client -connect HOST:443 -showcerts`
+- For Sourcegraph 5.1.5+, also configure `experimentalFeatures.tls.external` in site configuration
+
+### Repository Permissions
+
+When enabling `authorization`, consider these security implications:
+- Requires tokens with both read and write access to repositories for proper permission syncing
+- Without write access, conflicts may arise between user-centric and repo-centric permission sync
+- Internal repositories can be marked as public with `markInternalReposAsPublic` if organizational structure permits
+
+### Webhook Security
+
+GitHub webhooks configured through the deprecated `webhooks` property should be migrated to the new [incoming webhooks configuration](/admin/config/webhooks/incoming):
+- Webhook secrets provide authentication and prevent spoofing
+- Proper webhook configuration enables real-time permission updates
+
+## Common Examples
+
+### Basic Repository Sync
+```json
+{
+  "url": "https://github.com",
+  "token": "ghp_xxxxxxxxxxxxxxxxxxxx",
+  "repos": [
+    "kubernetes/kubernetes",
+    "golang/go"
+  ]
+}
+```
+
+### Organization-wide Sync with Exclusions
+```json
+{
+  "url": "https://github.com", 
+  "token": "ghp_xxxxxxxxxxxxxxxxxxxx",
+  "orgs": ["myorg"],
+  "exclude": [
+    {"name": "myorg/legacy-repo"},
+    {"archived": true}
+  ]
+}
+```
+
+### Advanced Query with Custom Path Pattern
+```json
+{
+  "url": "https://github.enterprise.com",
+  "token": "ghp_xxxxxxxxxxxxxxxxxxxx", 
+  "repositoryQuery": ["org:myorg language:go stars:>10"],
+  "repositoryPathPattern": "code/{nameWithOwner}",
+  "gitURLType": "ssh"
+}
+```
+
+### GitHub Enterprise with Authorization
+```json
+{
+  "url": "https://github.enterprise.com",
+  "token": "ghp_xxxxxxxxxxxxxxxxxxxx",
+  "orgs": ["engineering", "devops"],
+  "authorization": {
+    "markInternalReposAsPublic": true
+  },
+  "certificate": "-----BEGIN CERTIFICATE-----\n..."
+}
+```
+
+### Rate Limited Configuration
+```json
+{
+  "url": "https://github.com",
+  "token": "ghp_xxxxxxxxxxxxxxxxxxxx", 
+  "repositoryQuery": ["affiliated"],
+  "rateLimit": {
+    "enabled": true,
+    "requestsPerHour": 3000
+  }
+}
+```
+
+## Best Practices
+
+### Token Management
+
+1. **Use GitHub Apps** when possible instead of personal access tokens for better security and scalability
+2. **Create dedicated service accounts** for Sourcegraph rather than using personal tokens
+3. **Implement token rotation** policies to regularly refresh access tokens
+4. **Audit token permissions** regularly to ensure they follow least-privilege principles
+
+### Repository Organization
+
+1. **Use consistent naming patterns** with `repositoryPathPattern` to maintain organization
+2. **Leverage exclusion patterns** to filter out unwanted repositories efficiently
+3. **Prefer specific repository lists** over broad queries when possible for better performance
+4. **Implement repository archival policies** to exclude archived repositories from active search
+
+### Performance Optimization
+
+1. **Configure appropriate rate limits** based on your GitHub instance's capacity
+2. **Use repository queries wisely** - avoid complex search queries that may hit rate limits
+3. **Enable caching for large organizations** using `authorization.groupsCacheTTL` when appropriate
+4. **Monitor sync performance** and adjust `repoListUpdateInterval` in site configuration if needed
+
+### Permission Management
+
+1. **Enable authorization** for private repositories to ensure proper access control
+2. **Configure webhook support** for real-time permission updates
+3. **Use write access tokens** for permission syncing to avoid conflicts
+4. **Regularly audit repository access** to ensure permissions remain appropriate
+
+### Maintenance
+
+1. **Monitor connection health** through the site admin interface
+2. **Keep certificates updated** for GitHub Enterprise instances
+3. **Review and update exclusion patterns** as your repository landscape changes
+4. **Test configuration changes** in a staging environment when possible
diff --git a/docs/admin/code_hosts/gitlab.mdx b/docs/admin/code_hosts/gitlab.mdx
index 843d5ab18..fe8bdc575 100644
--- a/docs/admin/code_hosts/gitlab.mdx
+++ b/docs/admin/code_hosts/gitlab.mdx
@@ -338,6 +338,177 @@ The Sourcegraph instance's site admin must [update the `corsOrigin` site config
 ```
 {/* SCHEMA_SYNC_END: admin/code_hosts/gitlab.schema.json */}
 
+## Configuration Notes
+
+GitLab connections provide flexible configuration options for different deployment scenarios:
+
+- **Project Selection**: Use `projects` for specific repositories, `projectQuery` for API-based filtering, and `exclude` for fine-grained exclusions
+- **API Queries**: The `projectQuery` field supports GitLab API parameters like `?membership=true&archived=false` and group paths like `groups/mygroup/projects`
+- **Path Patterns**: The `repositoryPathPattern` field controls repository naming in Sourcegraph - ensure uniqueness across code hosts
+- **Internal Repositories**: GitLab's internal repository visibility can be handled via `markInternalReposAsPublic` for easier access
+
+### Rate Limiting Configuration
+
+GitLab connections include rate limiting to manage API usage:
+- Default: 36,000 requests per hour with rate limiting enabled
+- GitLab.com enforces stricter rate limits for unauthenticated requests
+- Self-managed instances may have different limits based on configuration
+
+### Token Configuration
+
+The `token` field supports different token types:
+- **Personal Access Token (PAT)**: Recommended for most use cases with `api` and `read_repository` scopes
+- **OAuth Token**: Used with OAuth authentication flows, includes refresh token support
+- **Project Access Token**: GitLab 13.10+ feature for project-specific access
+
+## Security Considerations
+
+### Token Security and Scoping
+
+**Personal Access Tokens**: Grant broad access equivalent to the user's permissions:
+- Use dedicated service accounts rather than personal tokens when possible
+- Required scopes: `api` for repository discovery, `read_repository` for cloning
+- Add `sudo` scope only when using external identity providers for permission syncing
+- Regularly rotate tokens and audit their usage
+
+**OAuth Tokens**: Provide more secure, time-limited access:
+- Tokens automatically refresh when expired
+- Support for fine-grained permissions
+- Better audit trail through OAuth application logs
+
+### Certificate Validation
+
+For self-managed GitLab instances with custom certificates:
+- Use the `certificate` field to specify custom CA certificates
+- Obtain certificates using: `openssl s_client -connect HOST:443 -showcerts`
+- Ensure certificate chain is complete for proper validation
+
+### Repository Permissions
+
+GitLab permission syncing has specific security requirements:
+- **OAuth Method**: Most secure, uses user's OAuth token for permission checks
+- **External Identity**: Requires admin token with `sudo` scope, matches users via external auth providers
+- **Username Method**: Least secure, assumes username equivalency - only use with `http-header` auth
+
+### Internal Repository Access
+
+GitLab's internal repositories require careful configuration:
+- Setting `markInternalReposAsPublic: true` makes internal repos visible to all Sourcegraph users
+- Consider organizational policies before enabling this setting
+- Alternative: Use proper permission syncing to maintain GitLab's access controls
+
+## Common Examples
+
+### Basic Project Sync
+```json
+{
+  "url": "https://gitlab.com",
+  "token": "glpat-xxxxxxxxxxxxxxxxxxxx",
+  "projects": [
+    {"name": "gitlab-org/gitlab"},
+    {"name": "my-group/my-project"}
+  ]
+}
+```
+
+### Organization-wide Sync with Exclusions
+```json
+{
+  "url": "https://gitlab.example.com",
+  "token": "glpat-xxxxxxxxxxxxxxxxxxxx",
+  "projectQuery": [
+    "groups/engineering/projects?archived=false",
+    "?membership=true&visibility=private"
+  ],
+  "exclude": [
+    {"name": "engineering/deprecated-project"},
+    {"pattern": "^experimental/.*"}
+  ]
+}
+```
+
+### Self-managed GitLab with Authorization
+```json
+{
+  "url": "https://gitlab.company.com",
+  "token": "glpat-xxxxxxxxxxxxxxxxxxxx",
+  "projectQuery": ["?membership=true"],
+  "authorization": {
+    "identityProvider": {
+      "type": "oauth"
+    }
+  },
+  "certificate": "-----BEGIN CERTIFICATE-----\n..."
+}
+```
+
+### Advanced Query with Custom Path Pattern
+```json
+{
+  "url": "https://gitlab.com",
+  "token": "glpat-xxxxxxxxxxxxxxxxxxxx",
+  "projectQuery": [
+    "groups/kubernetes/projects?visibility=public&order_by=last_activity_at",
+    "?search=docker&sort=desc"
+  ],
+  "repositoryPathPattern": "gitlab/{pathWithNamespace}",
+  "markInternalReposAsPublic": true
+}
+```
+
+### High-volume Configuration
+```json
+{
+  "url": "https://gitlab.enterprise.com",
+  "token": "glpat-xxxxxxxxxxxxxxxxxxxx",
+  "projectQuery": ["groups/bigorg/projects"],
+  "rateLimit": {
+    "enabled": true,
+    "requestsPerHour": 20000
+  },
+  "exclude": [
+    {"emptyRepos": true}
+  ]
+}
+```
+
+## Best Practices
+
+### Token Management
+
+1. **Use dedicated service accounts** instead of personal tokens for production deployments
+2. **Implement token rotation** policies to regularly refresh access tokens
+3. **Audit token permissions** regularly to ensure least-privilege access
+4. **Use OAuth tokens** when possible for better security and automatic refresh
+
+### Repository Organization
+
+1. **Use consistent naming patterns** with `repositoryPathPattern` to maintain organization
+2. **Leverage project queries** for dynamic repository discovery rather than static lists
+3. **Implement exclusion patterns** to filter out unwanted repositories (archived, empty, experimental)
+4. **Group related projects** using GitLab groups and subgroups for better organization
+
+### Performance Optimization
+
+1. **Configure appropriate rate limits** based on your GitLab instance's capacity
+2. **Use specific project queries** rather than broad searches to reduce API calls
+3. **Monitor API usage** to avoid hitting GitLab's rate limits
+4. **Enable proper caching** by configuring reasonable sync intervals
+
+### Permission Management
+
+1. **Choose the right permission method** for your authentication setup
+2. **Test permission syncing** thoroughly before deploying to production
+3. **Use OAuth authentication** when possible for better security and user experience
+4. **Regularly audit repository access** to ensure permissions remain appropriate
+
+### Maintenance
+
+1. **Monitor connection health** through the site admin interface
+2. **Keep certificates updated** for self-managed GitLab instances
+3. **Review and update project queries** as your repository landscape changes
+4. **Test configuration changes** in a staging environment when possible
+
 ## Access token scopes
 
 Sourcegraph requires an access token with `api` permissions (and `sudo`, if you are using an `external` identity provider type). These permissions are required for the following reasons:
diff --git a/docs/admin/code_hosts/gitolite.mdx b/docs/admin/code_hosts/gitolite.mdx
index 17e2a0a2b..e0b903bc0 100644
--- a/docs/admin/code_hosts/gitolite.mdx
+++ b/docs/admin/code_hosts/gitolite.mdx
@@ -63,3 +63,56 @@ To connect Gitolite to Sourcegraph:
 }
 ```
 {/* SCHEMA_SYNC_END: admin/code_hosts/gitolite.schema.json */}
+
+## Configuration Notes
+
+- **SSH Authentication Required**: Gitolite requires SSH key-based authentication. Ensure your Sourcegraph instance has proper SSH access to the Gitolite server.
+- **Prefix Configuration**: The `prefix` field determines how repository names appear in Sourcegraph. Use a unique prefix to avoid conflicts with other code hosts.
+- **Host Format**: The `host` field accepts both simple Git SSH URLs (e.g., `git@gitolite.example.com`) and full SSH URLs with custom ports (e.g., `ssh://git@gitolite.example.com:2222/`).
+
+## Security Considerations
+
+- **SSH Key Management**: Store SSH private keys securely and rotate them regularly. Use dedicated service accounts for Sourcegraph access.
+- **Network Access**: Ensure Sourcegraph can reach the Gitolite server on the required SSH port (typically 22).
+- **Repository Visibility**: By default, all configured repositories are visible to all Sourcegraph users. Configure repository permissions appropriately.
+- **Deprecated Fields**: The `phabricator` and `phabricatorMetadataCommand` fields are deprecated and should not be used.
+
+## Common Examples
+
+### Basic Gitolite Configuration
+
+```json
+{
+  "host": "git@gitolite.example.com",
+  "prefix": "gitolite.example.com/",
+  "exclude": [
+    {
+      "name": "secret-repo"
+    },
+    {
+      "pattern": ".*private.*"
+    }
+  ]
+}
+```
+
+### Custom SSH Port
+
+```json
+{
+  "host": "ssh://git@gitolite.example.com:2222/",
+  "prefix": "gitolite.example.com/",
+  "exclude": [
+    {
+      "pattern": ".*test.*"
+    }
+  ]
+}
+```
+
+## Best Practices
+
+- **Use Meaningful Prefixes**: Choose descriptive prefixes that clearly identify the Gitolite instance (e.g., `gitolite.mycompany.com/`).
+- **Regular Exclusion Patterns**: Use the `exclude` field to filter out test repositories, temporary branches, or sensitive repositories.
+- **Monitor SSH Connectivity**: Regularly verify that SSH authentication continues to work between Sourcegraph and Gitolite.
+- **Documentation**: Document your Gitolite configuration for team members, especially SSH key management procedures.
diff --git a/docs/admin/code_hosts/other.mdx b/docs/admin/code_hosts/other.mdx
index 945bf3185..9bcde413d 100644
--- a/docs/admin/code_hosts/other.mdx
+++ b/docs/admin/code_hosts/other.mdx
@@ -114,3 +114,83 @@ Repositories must be listed individually:
 }
 ```
 {/* SCHEMA_SYNC_END: admin/code_hosts/other_external_service.schema.json */}
+
+## Configuration Notes
+
+- **Repository Path Pattern**: The `repositoryPathPattern` field controls how repository names appear in Sourcegraph. Use `{base}` for the clone URL base and `{repo}` for the repository path.
+- **Manual Repository Listing**: Unlike other code hosts, repositories must be listed individually in the `repos` array - automatic discovery is not supported.
+- **SSH Configuration**: SSH access requires proper authentication setup between Sourcegraph and your Git server.
+- **Local Repository Support**: Use the `root` field for syncing local Git repositories when using Cody App with `src-serve-local`.
+
+## Security Considerations
+
+- **SSH Key Management**: For SSH URLs, ensure SSH keys are properly configured and securely stored.
+- **Network Access**: Verify Sourcegraph can reach your Git server on the required ports (SSH: 22, HTTP/HTTPS: 80/443).
+- **Authentication Tokens**: For HTTPS URLs with tokens, store access tokens securely and rotate them regularly.
+- **Repository Visibility**: Consider using `makeReposPublicOnDotCom` carefully to avoid exposing private repositories.
+
+## Common Examples
+
+### HTTPS Git Server
+
+```json
+{
+  "url": "https://git.example.com/repos",
+  "repos": [
+    "project1/app",
+    "project1/api",
+    "project2/frontend"
+  ],
+  "repositoryPathPattern": "git.example.com/{repo}"
+}
+```
+
+### SSH Git Server with Custom Port
+
+```json
+{
+  "url": "ssh://git@git.example.com:2222/",
+  "repos": [
+    "infrastructure/ansible",
+    "infrastructure/terraform"
+  ],
+  "repositoryPathPattern": "{base}/{repo}",
+  "exclude": [
+    {
+      "pattern": ".*temp.*"
+    }
+  ]
+}
+```
+
+### Local Repository Sync
+
+```json
+{
+  "repos": ["src-serve-local"],
+  "root": "/path/to/local/repos",
+  "repositoryPathPattern": "local/{repo}"
+}
+```
+
+### Git Server with Authentication Token
+
+```json
+{
+  "url": "https://git.example.com/?access_token=ghp_xxxxxxxxxxxx",
+  "repos": [
+    "team-a/service1",
+    "team-a/service2",
+    "team-b/frontend"
+  ],
+  "repositoryPathPattern": "internal/{repo}"
+}
+```
+
+## Best Practices
+
+- **Unique Repository Names**: Ensure the `repositoryPathPattern` generates unique names that don't conflict with other code hosts.
+- **Meaningful Patterns**: Use descriptive patterns that help users identify the source of repositories (e.g., `internal-git/{repo}`).
+- **Regular Exclusions**: Use `exclude` patterns to filter out temporary, test, or sensitive repositories.
+- **Test Connectivity**: Verify network connectivity and authentication before adding large numbers of repositories.
+- **Monitor Performance**: Be mindful that manual repository listing doesn't scale as well as automatic discovery from other code hosts.
diff --git a/docs/admin/code_hosts/phabricator.mdx b/docs/admin/code_hosts/phabricator.mdx
index 488be411e..4b5c42b7c 100644
--- a/docs/admin/code_hosts/phabricator.mdx
+++ b/docs/admin/code_hosts/phabricator.mdx
@@ -95,3 +95,59 @@ The Sourcegraph instance's site admin must [update the `corsOrigin` site config
 }
 ```
 {/* SCHEMA_SYNC_END: admin/code_hosts/phabricator.schema.json */}
+
+## Configuration Notes
+
+- **Limited Support**: Phabricator support is limited and not expected to evolve due to Phabricator's end-of-life announcement.
+- **Token vs Repos**: At least one of `token` or `repos` must be provided. Use `token` for automatic discovery or `repos` for manual mapping.
+- **Case-Sensitive Callsigns**: Repository callsigns are case-sensitive and must match exactly as configured in Phabricator.
+- **Repository Association**: Sourcegraph creates links to Phabricator pages but doesn't sync the actual repository content from Phabricator.
+
+## Security Considerations
+
+- **API Token Management**: Store Conduit API tokens securely and limit their scope to necessary operations.
+- **CORS Configuration**: Update Sourcegraph's `corsOrigin` setting to allow the Phabricator extension to communicate with your instance.
+- **Network Access**: Ensure Sourcegraph can reach your Phabricator instance over HTTPS.
+- **Token Rotation**: Regularly rotate API tokens and update configurations accordingly.
+
+## Common Examples
+
+### Basic Configuration with Token
+
+```json
+{
+  "url": "https://phabricator.example.com",
+  "token": "api-abcdefghijklmnop"
+}
+```
+
+### Manual Repository Mapping
+
+```json
+{
+  "url": "https://phabricator.example.com",
+  "repos": [
+    { "path": "github.com/myorg/frontend", "callsign": "FRONT" },
+    { "path": "github.com/myorg/backend", "callsign": "BACK" }
+  ]
+}
+```
+
+### Mixed Configuration
+
+```json
+{
+  "url": "https://phabricator.example.com",
+  "token": "api-abcdefghijklmnop",
+  "repos": [
+    { "path": "gitolite.example.com/special-repo", "callsign": "SPEC" }
+  ]
+}
+```
+
+## Best Practices
+
+- **Verify Repository Paths**: Use Phabricator's `diffusion.repository.search` API to verify that Sourcegraph repository paths match normalized URIs.
+- **Test Native Extension**: Install the native Phabricator extension for better user experience compared to browser extensions.
+- **Monitor Deprecation**: Plan migration away from Phabricator due to its announced end-of-life status.
+- **Troubleshooting**: Use the Conduit API testing interface to verify token permissions and repository accessibility.
diff --git a/docs/admin/config/settings.mdx b/docs/admin/config/settings.mdx
index 2f1a2656a..06af2b1ae 100644
--- a/docs/admin/config/settings.mdx
+++ b/docs/admin/config/settings.mdx
@@ -150,6 +150,172 @@ Settings options and their default values are shown below.
 ```
 {/* SCHEMA_SYNC_END: admin/config/settings.schema.json */}
 
+## 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
diff --git a/docs/admin/config/site_config.mdx b/docs/admin/config/site_config.mdx
index 8ee7ec32d..c79768afc 100644
--- a/docs/admin/config/site_config.mdx
+++ b/docs/admin/config/site_config.mdx
@@ -937,6 +937,181 @@ You can check the container logs to see if you have made any typos or mistakes i
 ```
 {/* SCHEMA_SYNC_END: admin/config/site.schema.json */}
 
+## 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.
diff --git a/docs/admin/repo/perforce.mdx b/docs/admin/repo/perforce.mdx
index 71b991870..14b526c9b 100644
--- a/docs/admin/repo/perforce.mdx
+++ b/docs/admin/repo/perforce.mdx
@@ -337,6 +337,86 @@ Add `"batchChanges.enablePerforce": true` to `experimentalFeatures` in the [site
 ```
 {/* SCHEMA_SYNC_END: admin/code_hosts/perforce.schema.json */}
 
+## Configuration Notes
+
+- **p4-fusion Recommended**: Use the `fusionClient` configuration for better performance compared to `git p4`.
+- **Depot Types**: Only "local" type depots are supported for synchronization.
+- **User Permissions**: The `p4.user` must have appropriate permissions for basic operations, and "super" access level if repository permissions are mirrored.
+- **Ticket Authentication**: Use `p4 -u <p4.user> login -p -a` to obtain ticket values for `p4.passwd`.
+- **Repository Path Pattern**: The `{depot}` variable in `repositoryPathPattern` is replaced with the Perforce depot path.
+
+## Security Considerations
+
+- **Ticket Management**: Store Perforce tickets securely and create tickets that never expire for service accounts.
+- **User Permissions**: Grant minimal required permissions to the Perforce user account used by Sourcegraph.
+- **SSL Connections**: Use SSL connections (`ssl:` prefix) for Perforce server connections when possible.
+- **IP Restrictions**: Configure IP-based rules carefully when using file-level permissions with `enforceIPRestrictions`.
+- **Permission Boundaries**: Align depot configurations with permission boundaries to maintain security.
+
+## Common Examples
+
+### Basic Perforce Configuration
+
+```json
+{
+  "p4.port": "ssl:perforce.example.com:1666",
+  "p4.user": "sourcegraph-service",
+  "p4.passwd": "6211C5E719EDE6925855039E8F5CC3D2",
+  "depots": [
+    "//Sourcegraph/",
+    "//Tools/"
+  ],
+  "fusionClient": {
+    "enabled": true,
+    "lookAhead": 2000
+  }
+}
+```
+
+### Configuration with Permissions
+
+```json
+{
+  "p4.port": "ssl:perforce.example.com:1666",
+  "p4.user": "admin",
+  "p4.passwd": "6211C5E719EDE6925855039E8F5CC3D2",
+  "depots": [
+    "//Depot/Frontend/",
+    "//Depot/Backend/",
+    "//Depot/Common/"
+  ],
+  "authorization": {
+    "subRepoPermissions": true
+  },
+  "repositoryPathPattern": "perforce/{depot}"
+}
+```
+
+### Subdirectory Permission Boundaries
+
+```json
+{
+  "p4.port": "tcp:perforce.example.com:1666",
+  "p4.user": "readonly",
+  "p4.passwd": "ABCDEF1234567890",
+  "depots": [
+    "//Project/main-dev/",
+    "//Project/release/frontend/",
+    "//Project/release/backend/"
+  ],
+  "maxChanges": 5000
+}
+```
+
+## Best Practices
+
+- **Use SSL Connections**: Always use SSL (`ssl:` prefix) for production Perforce connections.
+- **Enable p4-fusion**: Configure `fusionClient` with appropriate `lookAhead` values for better sync performance.
+- **Plan Permission Boundaries**: Design depot configurations around permission boundaries to avoid complex sub-repository permissions.
+- **Monitor Changelist Mapping**: When using experimental changelist ID features, monitor background mapping jobs.
+- **Regular Ticket Rotation**: Establish procedures for rotating Perforce tickets without service interruption.
+- **Test Permissions**: Verify that repository permissions work correctly after configuration changes.
+
 Batch Changes does not support repos that use sub-repo permissions, so in order to use batch changes with Perforce depots, the code host cannot use [file-level permissions](#file-level-permissions).
 
 When a Batch Change is published, it is sent as a shelved changelist to the server configured in the code host. The Changelist Id is displayed in the UI for the user to use for managing the shelved changelist.

From 47cd7cab6477a87cdfd08d75b1075a858dc1057e Mon Sep 17 00:00:00 2001
From: Warren Gifford <warrenbruceg@gmail.com>
Date: Wed, 25 Jun 2025 23:13:40 -0700
Subject: [PATCH 2/2] Fix SCHEMA_SYNC_END marker position for github.mdx

Move end marker from line 586 to line 551 to properly separate
auto-generated schema content from static educational content.

This ensures the schema sync tool only replaces the JSON schema
and preserves the Configuration Notes, Security Considerations,
and other valuable documentation.
---
 docs/admin/code_hosts/github.mdx | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/docs/admin/code_hosts/github.mdx b/docs/admin/code_hosts/github.mdx
index ccc01a9d3..4b4c39ed3 100644
--- a/docs/admin/code_hosts/github.mdx
+++ b/docs/admin/code_hosts/github.mdx
@@ -548,6 +548,7 @@ GitHub connections support the following configuration options, which are specif
 	//   ]
 }
 ```
+{/* SCHEMA_SYNC_END: admin/code_hosts/github.schema.json */}
 
 ## Default branch
 
@@ -583,8 +584,6 @@ If you would like to sync all public repositories while omitting archived repos,
     ]
 }
 ```
-{/* SCHEMA_SYNC_END: admin/code_hosts/github.schema.json */}
-
 ## Configuration Notes
 
 The GitHub connection schema provides several configuration patterns for different use cases: