diff --git a/docs/admin/code_hosts/aws_codecommit.mdx b/docs/admin/code_hosts/aws_codecommit.mdx
index 8fb8fcac8..c19045267 100644
--- a/docs/admin/code_hosts/aws_codecommit.mdx
+++ b/docs/admin/code_hosts/aws_codecommit.mdx
@@ -114,6 +114,116 @@ To add CodeCommit repositories in Docker Container:
 ```
 {/* SCHEMA_SYNC_END: admin/code_hosts/aws_codecommit.schema.json */}
 
+## Configuration Notes
+
+### Authentication Requirements
+- AWS CodeCommit requires Git credentials (username/password) for HTTPS cloning
+- IAM user must have `AWSCodeCommitReadOnly` policy attached
+- Git credentials are generated through AWS IAM console
+
+### Repository Discovery
+- All repositories in the specified region are synced by default
+- Use `exclude` to prevent specific repositories from being synced
+- Supports exclusion by repository name or ARN
+
+### Regional Configuration
+- Each AWS region requires a separate code host connection
+- Default region is `us-east-1` if not specified
+- Ensure `repositoryPathPattern` includes region for uniqueness
+
+## Security Considerations
+
+### IAM and Access Management
+- Use dedicated IAM users with minimal required permissions
+- Git credentials are separate from AWS API keys
+- Consider using IAM roles for EC2-hosted Sourcegraph instances (future enhancement)
+- Regularly rotate Git credentials according to security policies
+
+### Network Security
+- Ensure Sourcegraph can access CodeCommit endpoints for your region
+- HTTPS cloning uses port 443
+- SSH cloning requires port 22 and key management
+
+### Credential Storage
+- Store Git credentials securely
+- Use environment variables or secure secret management
+- Avoid committing credentials to configuration files
+
+## Common Examples
+
+### Basic HTTPS Configuration
+```json
+{
+  "region": "us-west-2",
+  "accessKeyID": "AKIA...",
+  "secretAccessKey": "secret-key",
+  "gitCredentials": {
+    "username": "git-username",
+    "password": "git-password"
+  },
+  "repositoryPathPattern": "codecommit-{region}/{name}"
+}
+```
+
+### Multi-Region Setup
+```json
+{
+  "region": "eu-central-1",
+  "accessKeyID": "AKIA...",
+  "secretAccessKey": "secret-key", 
+  "gitCredentials": {
+    "username": "git-username",
+    "password": "git-password"
+  },
+  "repositoryPathPattern": "git-codecommit.eu-central-1.amazonaws.com/{name}",
+  "exclude": [
+    {"name": "legacy-repo"},
+    {"id": "arn:aws:codecommit:eu-central-1:123456789012:archive-repo"}
+  ]
+}
+```
+
+### SSH Configuration
+```json
+{
+  "region": "us-east-1",
+  "accessKeyID": "AKIA...",
+  "secretAccessKey": "secret-key",
+  "gitURLType": "ssh",
+  "gitSSHKeyID": "ssh-key-id",
+  "gitSSHCredential": {
+    "privateKey": "base64-encoded-private-key",
+    "passphrase": "optional-passphrase"
+  }
+}
+```
+
+## Best Practices
+
+### Setup and Configuration
+- Create dedicated IAM users for Sourcegraph integration
+- Use meaningful `repositoryPathPattern` to avoid naming conflicts
+- Configure separate connections for different AWS regions
+- Test connections with a small set of repositories first
+
+### Security
+- Follow AWS IAM best practices for access keys
+- Use Git credentials with appropriate scope limitations
+- Implement regular credential rotation schedules
+- Monitor CloudTrail logs for CodeCommit access patterns
+
+### Performance
+- Use exclude patterns to limit repository scope
+- Consider repository size when planning sync schedules
+- Monitor AWS service limits and quotas
+- Plan for regional latency considerations
+
+### Maintenance
+- Keep IAM policies updated with AWS service changes
+- Monitor for deprecated authentication methods
+- Plan migration strategies for future IAM role support
+- Regularly review repository inclusion/exclusion patterns
+
 ### 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..c91dfc33a 100644
--- a/docs/admin/code_hosts/azuredevops.mdx
+++ b/docs/admin/code_hosts/azuredevops.mdx
@@ -129,6 +129,118 @@ Azure DevOps connections support the following configuration options, which are
 ```
 {/* SCHEMA_SYNC_END: admin/code_hosts/azuredevops.schema.json */}
 
+## Configuration Notes
+
+### Authentication Requirements
+- Azure DevOps requires Personal Access Tokens (PAT) for API access
+- Tokens must have access to "All accessible organizations" for connection checks
+- Required scopes: Code (Read), Project and Team, User Profile
+
+### Repository Discovery
+- Configure `orgs` to sync all repositories from specific organizations
+- Configure `projects` to sync repositories from specific projects (format: "org/project")
+- Use `exclude` to prevent specific repositories from being synced
+
+### Permission Model
+- Set `enforcePermissions: true` to sync user-level permissions
+- Requires OAuth provider configuration and third-party access enablement
+- Initial permissions sync may take time to complete
+
+## Security Considerations
+
+### Token Management
+- Personal Access Tokens provide broad access to Azure DevOps resources
+- Store tokens securely and rotate them regularly according to your security policy
+- Consider using dedicated service accounts for production deployments
+- Monitor token usage and expiration dates
+
+### OAuth Configuration
+- Third-party OAuth access must be enabled at the organization level
+- Users must authenticate with Azure DevOps to access private repositories
+- Consider organizational policies around external application access
+
+### Network Security
+- Ensure Sourcegraph can access dev.azure.com on port 443
+- Consider firewall rules for on-premises Azure DevOps Server instances
+- SSH access requires additional key management if using SSH cloning
+
+## Common Examples
+
+### Basic Organization Sync
+```json
+{
+  "url": "https://dev.azure.com/",
+  "username": "service-account",
+  "token": "personal-access-token",
+  "orgs": ["my-organization"],
+  "gitURLType": "http"
+}
+```
+
+### Project-Specific Configuration
+```json
+{
+  "url": "https://dev.azure.com/",
+  "username": "service-account", 
+  "token": "personal-access-token",
+  "projects": [
+    "my-org/project-1",
+    "my-org/project-2"
+  ],
+  "exclude": [
+    {"name": "my-org/project-1/legacy-repo"}
+  ]
+}
+```
+
+### Permissions Enforcement Setup
+```json
+{
+  "url": "https://dev.azure.com/",
+  "username": "service-account",
+  "token": "personal-access-token",
+  "orgs": ["my-organization"],
+  "enforcePermissions": true
+}
+```
+
+### SSH Cloning Configuration
+```json
+{
+  "url": "https://dev.azure.com/",
+  "username": "service-account",
+  "token": "personal-access-token",
+  "orgs": ["my-organization"],
+  "gitURLType": "ssh"
+}
+```
+
+## Best Practices
+
+### Setup and Configuration
+- Create dedicated service accounts with minimal required permissions
+- Use project-specific configurations when possible to limit scope
+- Test connections with small repository sets before full deployment
+- Configure exclude patterns to avoid syncing unnecessary repositories
+
+### Security
+- Regularly audit and rotate Personal Access Tokens
+- Enable permissions enforcement for sensitive repositories
+- Monitor OAuth application access at the organization level
+- Use HTTPS cloning unless SSH is specifically required
+
+### Performance
+- Prefer `projects` over `orgs` configuration for better performance
+- Monitor rate limit usage and adjust polling intervals if needed
+- Consider repository size and complexity when planning sync schedules
+- Use exclude patterns to optimize sync performance
+
+### Maintenance
+- Plan for OAuth application access policy changes
+- Monitor permissions sync status for users
+- Keep webhook configurations updated
+- Regularly review organization and project configurations
+
 ## 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..8409d07ca 100644
--- a/docs/admin/code_hosts/bitbucket_cloud.mdx
+++ b/docs/admin/code_hosts/bitbucket_cloud.mdx
@@ -208,6 +208,115 @@ Bitbucket Cloud connections support the following configuration options, which a
 ```
 {/* SCHEMA_SYNC_END: admin/code_hosts/bitbucket_cloud.schema.json */}
 
+## Configuration Notes
+
+### Authentication Methods
+Bitbucket Cloud supports two authentication approaches:
+- **Username and App Password**: Standard user credentials with application-specific password
+- **Workspace Access Token**: OAuth-based token scoped to specific workspace
+
+### Repository Discovery
+- The connection syncs all repositories for the configured user by default
+- Use `teams` to limit syncing to specific workspaces
+- Use `exclude` to prevent specific repositories from being synced (takes precedence over `teams`)
+
+### Rate Limiting Behavior
+- Sourcegraph respects Bitbucket Cloud's rate limits with exponential backoff
+- Requests are retried for up to 5 minutes before being dropped
+- Default internal rate limit: 7200 requests per hour
+
+## Security Considerations
+
+### Credential Management
+- App passwords provide repository-level access control
+- Workspace access tokens offer more granular permissions
+- Store credentials securely and rotate them regularly
+- Use separate service accounts for production deployments
+
+### Repository Access
+- Public repositories are accessible without authentication
+- Private repositories require proper credentials
+- Authorization enforcement requires matching authentication provider configuration
+
+### SSH vs HTTPS
+- HTTPS is the default and recommended clone method
+- SSH cloning requires additional key management setup
+- Consider firewall rules for SSH access (port 22)
+
+## Common Examples
+
+### Basic Username/App Password Setup
+```json
+{
+  "url": "https://bitbucket.org/",
+  "username": "service-account",
+  "appPassword": "app-password-value",
+  "teams": ["my-workspace"],
+  "repositoryPathPattern": "{host}/{nameWithOwner}"
+}
+```
+
+### Workspace Access Token Configuration
+```json
+{
+  "url": "https://bitbucket.org/",
+  "accessToken": "workspace-token-value",
+  "teams": ["my-workspace"],
+  "exclude": [
+    {"name": "my-workspace/legacy-repo"},
+    {"pattern": ".*-archive$"}
+  ]
+}
+```
+
+### SSH Cloning Setup
+```json
+{
+  "url": "https://bitbucket.org/",
+  "username": "service-account",
+  "appPassword": "app-password-value",
+  "gitURLType": "ssh",
+  "teams": ["my-workspace"]
+}
+```
+
+### Repository Permissions Enforcement
+```json
+{
+  "url": "https://bitbucket.org/",
+  "username": "service-account",
+  "appPassword": "app-password-value",
+  "authorization": {},
+  "teams": ["my-workspace"]
+}
+```
+
+## Best Practices
+
+### Setup and Configuration
+- Create dedicated service accounts for Sourcegraph integration
+- Use workspace access tokens when working with multiple workspaces
+- Configure `repositoryPathPattern` to avoid naming conflicts
+- Test connections with minimal repository sets before full deployment
+
+### Security
+- Regularly audit and rotate authentication credentials
+- Use repository permissions when dealing with sensitive code
+- Monitor rate limit usage and adjust request patterns if needed
+- Implement proper network security for SSH connections
+
+### Performance
+- Use exclude patterns to filter out unnecessary repositories
+- Configure appropriate rate limits based on your usage patterns
+- Monitor repository sync times and optimize large workspace configurations
+- Consider workspace-specific tokens for better performance isolation
+
+### Maintenance
+- Keep webhook configurations up to date
+- Monitor sync errors and connection health
+- Regularly review team and repository configurations
+- Plan for authentication provider changes when enforcing permissions
+
 ## 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..02ab036fe 100644
--- a/docs/admin/code_hosts/bitbucket_server.mdx
+++ b/docs/admin/code_hosts/bitbucket_server.mdx
@@ -331,3 +331,139 @@ Bitbucket Server / Bitbucket Data Center connections support the following confi
 }
 ```
 {/* SCHEMA_SYNC_END: admin/code_hosts/bitbucket_server.schema.json */}
+
+## Configuration Notes
+
+### Repository Discovery
+- **`repos`** - Explicit list in `"projectKey/repositorySlug"` format, with ordering preserved for sync priority
+- **`repositoryQuery`** - Supports special values (`"none"`, `"all"`) or Bitbucket API query parameters
+- **`exclude`** - Takes precedence over `repos` and `repositoryQuery`, supports name, ID, and pattern matching
+- **`excludePersonalRepositories`** - Useful for organizational policies that restrict personal repo access
+
+### Authentication Methods
+- **Personal Access Tokens** - Recommended for Bitbucket Server 5.5+ with read/write permissions as needed
+- **Username/Password** - Legacy method for older Bitbucket versions (5.4 and earlier)
+- **OAuth2** - Simplest permission setup, requires Bitbucket Server auth provider
+- **OAuth1** - More complex setup but works without requiring Bitbucket as auth provider
+
+### Performance & Security
+- **`rateLimit`** - Default 28,800 requests/hour (8/second) for API calls
+- **`gitURLType`** - Choose between `"http"` (default) or `"ssh"` for repository access
+- **Certificate validation** - Required for self-signed or internal CA certificates
+
+## Security Considerations
+
+### Token Management
+- Personal access tokens require **read** permissions minimum
+- **Write** permissions needed for Batch Changes functionality
+- Store tokens securely and implement regular rotation
+- For older versions, username/password credentials pose higher security risk
+
+### Permission Synchronization
+- Requires **exact username matching** between Sourcegraph and Bitbucket Server
+- **`auth.enableUsernameChanges: false`** must be set to prevent privilege escalation
+- Large user/repository counts significantly impact sync duration
+- Consider installing Sourcegraph Bitbucket Server plugin for faster sync
+
+### OAuth Configuration Security
+- OAuth1 setup requires generating and securely storing RSA key pairs
+- Consumer keys should use cryptographically random values
+- Allow user impersonation flag has security implications - use carefully
+- OAuth2 is generally more secure and simpler to configure
+
+## Common Examples
+
+### Basic Connection with Personal Access Token
+```json
+{
+  "url": "https://bitbucket.company.com/",
+  "username": "sourcegraph-service",
+  "token": "[REDACTED:bitbucket-pat]",
+  "repositoryQuery": ["?name=backend&projectname=WEB"],
+  "excludePersonalRepositories": true
+}
+```
+
+### OAuth2 with Repository Permissions
+```json
+{
+  "url": "https://bitbucket.company.com/", 
+  "username": "sourcegraph-service",
+  "token": "[REDACTED:bitbucket-pat]",
+  "repos": ["WEB/backend", "WEB/frontend", "MOBILE/ios-app"],
+  "authorization": {
+    "oauth2": true
+  }
+}
+```
+
+### OAuth1 Permission Setup
+```json
+{
+  "url": "https://bitbucket.company.com/",
+  "username": "admin-user",
+  "token": "[REDACTED:bitbucket-pat]",
+  "repositoryQuery": ["all"],
+  "exclude": [
+    {"pattern": "^ARCHIVE/.*"},
+    {"name": "TEST/deprecated-repo"}
+  ],
+  "authorization": {
+    "identityProvider": {
+      "type": "username"
+    },
+    "oauth": {
+      "consumerKey": "sourcegraph12345abcdef",
+      "signingKey": "[REDACTED:base64-encoded-private-key]"
+    }
+  }
+}
+```
+
+### Fast Permission Sync with Plugin
+```json
+{
+  "url": "https://bitbucket.company.com/",
+  "username": "sourcegraph-service", 
+  "token": "[REDACTED:bitbucket-pat]",
+  "repositoryQuery": ["?visibility=private"],
+  "authorization": {
+    "oauth2": true
+  },
+  "plugin": {
+    "permissions": "enabled"
+  }
+}
+```
+
+## Best Practices
+
+### Repository Management
+- Use `repositoryQuery` with specific filters rather than `"all"` for better performance
+- Implement `exclude` patterns for archived or deprecated projects
+- Set `excludePersonalRepositories: true` for organizational policies
+- Order `repos` list by sync priority (most important repositories first)
+
+### Authentication & Security
+- Prefer OAuth2 over OAuth1 for simpler and more secure setup
+- Use dedicated service accounts with minimal required permissions
+- Implement certificate validation for self-hosted instances
+- Regularly audit and rotate access tokens
+
+### Performance Optimization
+- Install the Sourcegraph Bitbucket Server plugin for faster permission syncing
+- Monitor and adjust rate limits based on Bitbucket Server capacity
+- Use specific repository queries rather than syncing all repositories
+- Consider excluding personal repositories to reduce sync overhead
+
+### Compliance & Monitoring
+- Document your permission synchronization strategy
+- Monitor sync duration and failures in large environments
+- Set up alerts for authentication failures or rate limit hits
+- Regularly review repository access patterns and cleanup unused repos
+
+### Troubleshooting
+- Test personal access token permissions through Bitbucket Server UI
+- Verify SSL certificates and network connectivity
+- Check Sourcegraph logs for OAuth setup errors
+- Monitor Bitbucket Server logs for API request patterns
diff --git a/docs/admin/code_hosts/gerrit.mdx b/docs/admin/code_hosts/gerrit.mdx
index 17457d8bb..df8246f0a 100644
--- a/docs/admin/code_hosts/gerrit.mdx
+++ b/docs/admin/code_hosts/gerrit.mdx
@@ -154,3 +154,122 @@ Gerrit connections support the following configuration options, which are specif
 }
 ```
 {/* SCHEMA_SYNC_END: admin/code_hosts/gerrit.schema.json */}
+
+## Configuration Notes
+
+### Authentication Requirements
+- Gerrit requires HTTP credentials for API access and repository cloning
+- The configured user must have access to all repositories intended for syncing
+- HTTP credentials are generated from the Gerrit web interface
+
+### Repository Discovery
+- Without `projects` configuration, all accessible projects are synced
+- Use `projects` to limit syncing to specific project names
+- Use `exclude` to prevent specific projects from being synced (takes precedence over `projects`)
+
+### Permission Integration
+- Setting `authorization: {}` enables repository permissions enforcement
+- Requires matching Gerrit authentication provider in site configuration
+- Users authenticate with their Gerrit HTTP credentials
+
+## Security Considerations
+
+### Credential Management
+- HTTP credentials provide access to Gerrit repositories and metadata
+- Store credentials securely using environment variables or secret management
+- Consider using dedicated service accounts with appropriate permissions
+- Regularly rotate credentials according to security policies
+
+### Access Control
+- Gerrit's built-in permission system integrates with Sourcegraph
+- Users must have valid Gerrit credentials to access private repositories
+- Repository visibility is controlled through Gerrit's project permissions
+
+### Network Security
+- Ensure Sourcegraph can access Gerrit server on configured ports
+- HTTPS is recommended for secure credential transmission
+- SSH cloning requires additional key management setup
+
+## Common Examples
+
+### Basic HTTP Authentication
+```json
+{
+  "url": "https://gerrit.example.com/",
+  "username": "service-account",
+  "password": "http-password",
+  "projects": [
+    "platform/core",
+    "platform/ui"
+  ]
+}
+```
+
+### Full Project Sync with Exclusions
+```json
+{
+  "url": "https://gerrit.example.com/",
+  "username": "service-account", 
+  "password": "http-password",
+  "exclude": [
+    {"name": "archived-project"},
+    {"name": "experimental/prototype"}
+  ]
+}
+```
+
+### SSH Cloning Configuration
+```json
+{
+  "url": "https://gerrit.example.com/",
+  "username": "service-account",
+  "password": "http-password",
+  "projects": ["platform/core"],
+  "gitSSHCredential": {
+    "privateKey": "base64-encoded-private-key"
+  }
+}
+```
+
+### Repository Permissions Enforcement
+```json
+{
+  "url": "https://gerrit.example.com/",
+  "username": "service-account",
+  "password": "http-password",
+  "projects": ["platform/core"],
+  "authorization": {}
+}
+```
+
+## Best Practices
+
+### Setup and Configuration
+- Create dedicated service accounts for Sourcegraph integration
+- Use specific project configurations rather than syncing all projects
+- Test connections with a minimal set of projects first
+- Ensure service account has appropriate access to target projects
+
+### Security
+- Implement regular credential rotation schedules
+- Use HTTPS for secure communication with Gerrit servers
+- Enable repository permissions when dealing with sensitive code
+- Monitor Gerrit access logs for unusual activity
+
+### Performance
+- Prefer specific project lists over syncing all projects
+- Use exclude patterns to filter out unnecessary repositories
+- Consider project size and complexity when planning sync schedules
+- Monitor sync performance and adjust configurations as needed
+
+### Maintenance
+- Keep authentication provider configurations synchronized
+- Regularly review project inclusion/exclusion patterns
+- Plan for Gerrit server upgrades and configuration changes
+- Monitor user permission sync status and resolve issues promptly
+
+### Integration Notes
+- Gerrit is in beta and may have limitations
+- Consider Gerrit's deprecation timeline when planning long-term usage
+- Test authentication provider integration thoroughly
+- Document any custom configuration requirements for your environment
diff --git a/docs/admin/code_hosts/github.mdx b/docs/admin/code_hosts/github.mdx
index 84cd878b7..d77721318 100644
--- a/docs/admin/code_hosts/github.mdx
+++ b/docs/admin/code_hosts/github.mdx
@@ -584,3 +584,116 @@ If you would like to sync all public repositories while omitting archived repos,
 }
 ```
 {/* SCHEMA_SYNC_END: admin/code_hosts/github.schema.json */}
+
+## Configuration Notes
+
+### Authorization Field Requirements
+When configuring repository permissions, the `authorization` field requires a corresponding GitHub authentication provider in the site configuration's `auth.providers` section with matching `url` values.
+
+### Certificate Configuration
+For GitHub Enterprise instances using self-signed or internal CA certificates, use the `certificate` field. Extract the certificate using:
+```bash
+openssl s_client -connect HOST:443 -showcerts < /dev/null 2> /dev/null | openssl x509 -outform PEM
+```
+
+### Repository Path Patterns
+The `repositoryPathPattern` controls how GitHub repositories map to Sourcegraph URLs. The pattern `{host}/{nameWithOwner}` ensures unique repository names across different code hosts. For example:
+- GitHub Enterprise at `https://github.example.com`
+- Repository `myorg/myrepo` 
+- Becomes `https://src.example.com/github.example.com/myorg/myrepo` on Sourcegraph
+
+### Repository Query Options
+Special `repositoryQuery` values have specific behaviors:
+- `public`: All public repos (GitHub Enterprise only, equivalent to `none` on GitHub.com)
+- `internal`: Internal repos (GitHub Enterprise only, uses Search API)
+- `affiliated`: Repos accessible to the token user (private with read access, owned public repos, public repos with write access)
+- `none`: No automatic syncing (manual configuration only)
+- Custom queries: Use GitHub advanced search syntax
+
+## Security Considerations
+
+### Token Scope Requirements
+**Critical**: The account associated with your token must have actual access to resources, not just the token scopes:
+- **Read access**: Token needs `repo` scope AND account must have read access to repositories
+- **Write access**: Token needs `repo` scope AND account must have write access to all repositories  
+- **Organization access**: Token needs `write:org` scope AND account must have admin access to organizations
+
+### Certificate Handling
+For internal certificates, escape the PEM format properly when adding to JSON configuration. Consider using tools like https://json-escape-text.now.sh for proper JSON escaping.
+
+### Rate Limit Bypass
+Always include a token for GitHub.com connections to avoid unauthenticated rate limits, even if you don't want automatic repository synchronization. A token without `repo` scope can be used solely for rate limit bypass.
+
+## Common Examples
+
+### Basic Single Repository
+```json
+{
+  "url": "https://github.com/",
+  "token": "<access token>",
+  "orgs": [],
+  "repos": ["kubernetes/kubernetes"]
+}
+```
+
+### Organization with Excluded Repositories
+```json
+{
+  "url": "https://github.example.com/",
+  "token": "<access token>",
+  "orgs": ["myorg"],
+  "exclude": [
+    {"name": "myorg/secret-repo"},
+    {"pattern": "^myorg/temp-.*"}
+  ]
+}
+```
+
+### Public Repositories Excluding Archived
+```json
+{
+  "url": "https://github.example.com/",
+  "gitURLType": "http",
+  "repositoryPathPattern": "devs/{nameWithOwner}",
+  "repositoryQuery": ["affiliated"],
+  "token": "TOKEN_WITH_PUBLIC_ACCESS",
+  "exclude": [{"archived": true}]
+}
+```
+
+### GitHub Enterprise with Internal Repository Access
+```json
+{
+  "url": "https://github.enterprise.com/",
+  "token": "<access token>",
+  "repositoryQuery": ["internal"],
+  "authorization": {
+    "markInternalReposAsPublic": true
+  }
+}
+```
+
+## Best Practices
+
+### Permission Syncing Setup
+1. Configure both read and write access for the token account when using repository permissions
+2. Without write access, conflicts occur between user-centric and repo-centric sync
+3. Consider disabling repo-centric permission sync if write access cannot be granted
+4. Set up webhooks for real-time permission updates
+
+### Repository Selection Strategy
+- Use `orgs` for complete organization syncing
+- Use `repos` for specific repository lists  
+- Use `repositoryQuery: ["affiliated"]` for user-accessible repositories
+- Combine with `exclude` patterns for fine-grained control
+
+### Rate Limit Management
+- Monitor search API usage when using custom `repositoryQuery` values
+- Use special values (`affiliated`, `public`, `none`) to avoid search API limits
+- Increase `repoListUpdateInterval` in site config if hitting search rate limits
+- Consider switching to `orgs` configuration instead of complex queries
+
+### GitHub App vs Token Selection
+- **GitHub Apps**: Recommended for better security, automatic token rotation, and webhook integration
+- **Personal Access Tokens**: Simpler setup, broader API compatibility
+- **Fine-grained Tokens**: Limited scope access, unsupported for GraphQL features like batch changes
diff --git a/docs/admin/code_hosts/gitlab.mdx b/docs/admin/code_hosts/gitlab.mdx
index 843d5ab18..20c64ecf1 100644
--- a/docs/admin/code_hosts/gitlab.mdx
+++ b/docs/admin/code_hosts/gitlab.mdx
@@ -338,6 +338,115 @@ The Sourcegraph instance's site admin must [update the `corsOrigin` site config
 ```
 {/* SCHEMA_SYNC_END: admin/code_hosts/gitlab.schema.json */}
 
+## Configuration Notes
+
+### Repository Discovery
+- **`projectQuery`** accepts multiple formats: simple queries like `"?archived=false"`, API endpoints like `"groups/mygroup/projects"`, or the special value `"none"` to disable auto-discovery
+- **`projects`** allows explicit specification by name (`{"name": "group/name"}`) or ID (`{"id": 42}`)
+- **`exclude`** takes precedence over both `projects` and `projectQuery`, supporting name, ID, or regex patterns
+
+### Authentication & Permissions
+- **OAuth Application** (recommended) - Uses user's OAuth token for repository access, requires GitLab as auth provider
+- **Administrator Token** - Requires sudo-level token with SAML/OIDC auth provider
+- **Username Matching** - Only safe with `http-header` authentication where usernames are immutable
+
+### Performance Settings
+- **`rateLimit`** - Default 36,000 requests/hour (10/second) to GitLab API
+- **`markInternalReposAsPublic`** - Makes internal GitLab repos public in Sourcegraph, bypassing permission syncs
+
+## Security Considerations
+
+### Token Security
+- Always use tokens with GitLab.com to avoid unauthenticated rate limits
+- **`read_api`** and **`read_repository`** scopes are minimum required
+- **`sudo`** scope needed only for external identity provider setup
+- Store tokens securely and rotate them regularly
+
+### Permission Synchronization
+- Repository permissions sync can take significant time with large user/repo counts
+- **OAuth method** is most secure and doesn't require admin privileges
+- **Username matching** method has security risks if usernames can change
+- **Administrator token** method requires careful identity provider configuration
+
+### Internal Repository Access
+- `markInternalReposAsPublic` bypasses GitLab's permission model
+- Only use when all Sourcegraph users should access all internal repositories
+- Consider security implications of making internal repos globally accessible
+
+## Common Examples
+
+### Basic GitLab.com Connection
+```json
+{
+  "url": "https://gitlab.com/",
+  "token": "glpat-xxxxxxxxxxxxxxxxxxxx",
+  "projectQuery": [
+    "projects?membership=true&archived=no",
+    "groups/myorg/projects"
+  ]
+}
+```
+
+### Self-hosted GitLab with OAuth Permissions
+```json
+{
+  "url": "https://gitlab.company.com/",
+  "token": "glpat-xxxxxxxxxxxxxxxxxxxx", 
+  "certificate": "-----BEGIN CERTIFICATE-----\n...",
+  "projectQuery": ["projects?membership=true"],
+  "authorization": {
+    "identityProvider": {
+      "type": "oauth"
+    }
+  },
+  "markInternalReposAsPublic": true
+}
+```
+
+### Filtered Repository Selection
+```json
+{
+  "url": "https://gitlab.com/",
+  "token": "glpat-xxxxxxxxxxxxxxxxxxxx",
+  "projects": [
+    {"name": "myorg/backend"},
+    {"name": "myorg/frontend"},
+    {"id": 12345}
+  ],
+  "exclude": [
+    {"pattern": ".*-archived$"},
+    {"name": "myorg/deprecated-project"}
+  ]
+}
+```
+
+## Best Practices
+
+### Repository Management
+- Use `projectQuery` for dynamic discovery based on GitLab attributes
+- Combine with `exclude` patterns to filter out unwanted repositories
+- Regularly review and clean up repository selections
+- Use specific project inclusion for sensitive or critical repos
+
+### Performance Optimization
+- Monitor rate limit usage and adjust `requestsPerHour` if needed
+- Use `markInternalReposAsPublic` carefully to reduce permission sync overhead
+- Consider excluding archived/forked repositories to reduce sync time
+- Implement repository name transformations to maintain consistent naming
+
+### Security & Compliance
+- Implement proper certificate validation for self-hosted instances
+- Use OAuth authentication for better security posture
+- Regularly audit repository access permissions
+- Set up monitoring for permission sync failures
+- Document your permission model for compliance audits
+
+### Troubleshooting
+- Test token permissions with curl commands against GitLab API
+- Monitor Sourcegraph logs for rate limit or permission errors
+- Verify SSL certificates for self-hosted GitLab instances
+- Check webhook configuration for real-time updates
+
 ## 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..de67503ae 100644
--- a/docs/admin/code_hosts/gitolite.mdx
+++ b/docs/admin/code_hosts/gitolite.mdx
@@ -63,3 +63,113 @@ To connect Gitolite to Sourcegraph:
 }
 ```
 {/* SCHEMA_SYNC_END: admin/code_hosts/gitolite.schema.json */}
+
+## Configuration Notes
+
+### Authentication Requirements
+- Gitolite connections require SSH authentication setup
+- SSH keys must be configured before creating the code host connection
+- The SSH user must have access to all repositories intended for syncing
+
+### Repository Discovery
+- All accessible repositories are synced by default
+- Use `exclude` to prevent specific repositories from being synced
+- Supports exclusion by exact name or regular expression pattern
+
+### Connection Setup
+- SSH authentication must be configured prior to adding the code host
+- The `host` field specifies the SSH connection string
+- The `prefix` field determines the repository naming pattern in Sourcegraph
+
+## Security Considerations
+
+### SSH Key Management
+- Use dedicated SSH keys for Sourcegraph integration
+- Store private keys securely using proper file permissions
+- Consider using SSH key passphrases for additional security
+- Regularly rotate SSH keys according to security policies
+
+### Access Control
+- Gitolite's repository access control is not enforced by Sourcegraph
+- All repositories accessible to the configured SSH user will be visible
+- Consider using dedicated Gitolite users with limited repository access
+
+### Network Security
+- Ensure Sourcegraph can access Gitolite server on SSH port (typically 22)
+- Configure firewall rules appropriately for SSH access
+- Consider using non-standard SSH ports for additional security
+
+## Common Examples
+
+### Basic SSH Configuration
+```json
+{
+  "host": "git@gitolite.example.com",
+  "prefix": "gitolite.example.com/",
+  "exclude": [
+    {"name": "test-repo"},
+    {"pattern": ".*-temp$"}
+  ]
+}
+```
+
+### Custom SSH Port Setup
+```json
+{
+  "host": "ssh://git@gitolite.example.com:2222/",
+  "prefix": "gitolite.example.com/",
+  "exclude": [
+    {"pattern": "^archive/.*"}
+  ]
+}
+```
+
+### Multiple Gitolite Instances
+```json
+{
+  "host": "git@internal-gitolite.company.com",
+  "prefix": "internal-git/",
+  "exclude": [
+    {"pattern": ".*secret.*"},
+    {"name": "legacy-system"}
+  ]
+}
+```
+
+## Best Practices
+
+### Setup and Configuration
+- Test SSH connectivity manually before configuring the code host
+- Use meaningful prefix patterns to avoid repository name conflicts
+- Configure exclude patterns to filter out temporary or test repositories
+- Verify SSH key permissions and ownership on the Sourcegraph server
+
+### Security
+- Use dedicated SSH keys specifically for Sourcegraph integration
+- Implement proper SSH key rotation schedules
+- Consider using SSH key passphrases with secure key storage
+- Monitor SSH access logs for unusual activity
+
+### Performance
+- Use exclude patterns to limit the scope of repository syncing
+- Consider the size and number of repositories when planning sync schedules
+- Monitor network performance for large repository synchronizations
+- Plan for SSH connection limits and timeouts
+
+### Maintenance
+- Regularly review repository inclusion/exclusion patterns
+- Keep SSH configurations updated with infrastructure changes
+- Plan for Gitolite server migrations and key rotations
+- Monitor sync errors and connectivity issues
+
+### Migration Considerations
+- Gitolite is not actively recommended for new installations
+- Consider migrating to more actively supported Git hosting solutions
+- Plan transition strategies for existing Gitolite repositories
+- Evaluate alternatives like GitLab, GitHub Enterprise, or Bitbucket
+
+### Troubleshooting
+- Verify SSH connectivity using `ssh -T git@gitolite.example.com`
+- Check SSH key permissions (600 for private key, 644 for public key)
+- Ensure SSH agent is configured properly if using key passphrases
+- Review Gitolite server logs for access and authentication issues
diff --git a/docs/admin/code_hosts/other.mdx b/docs/admin/code_hosts/other.mdx
index 945bf3185..39262fd8c 100644
--- a/docs/admin/code_hosts/other.mdx
+++ b/docs/admin/code_hosts/other.mdx
@@ -114,3 +114,134 @@ Repositories must be listed individually:
 }
 ```
 {/* SCHEMA_SYNC_END: admin/code_hosts/other_external_service.schema.json */}
+
+## Configuration Notes
+
+### Use Cases
+- Generic Git host connections are for unsupported or custom Git hosting solutions
+- Use only when your Git host doesn't have a dedicated Sourcegraph integration
+- Requires manual specification of repository lists
+
+### Repository Management
+- Repositories must be listed individually in the `repos` array
+- Repository names should match the path after the base URL
+- Use `exclude` patterns to filter out unwanted repositories
+
+### URL Configuration
+- Supports HTTP, HTTPS, SSH, and Git protocols
+- SSH access requires proper key configuration
+- Include authentication tokens in URLs when necessary
+
+## Security Considerations
+
+### Authentication
+- Embed authentication tokens directly in URLs when required
+- Use environment variables for sensitive credentials
+- Consider using SSH keys for private repository access
+- Regularly rotate authentication credentials
+
+### Access Control
+- Generic Git hosts do not enforce repository permissions
+- All configured repositories will be accessible to Sourcegraph users
+- Consider using dedicated Git users with limited repository access
+
+### Network Security
+- Ensure Sourcegraph can access Git host on required ports
+- SSH connections require port 22 access and key exchange
+- HTTPS connections require port 443 access
+- Consider firewall rules for custom Git protocols
+
+## Common Examples
+
+### HTTPS with Authentication Token
+```json
+{
+  "url": "https://git.example.com/",
+  "repos": [
+    "myorg/project1",
+    "myorg/project2"
+  ],
+  "repositoryPathPattern": "git.example.com/{repo}"
+}
+```
+
+### SSH Configuration
+```json
+{
+  "url": "ssh://git@git.example.com:2222/",
+  "repos": [
+    "platform/core",
+    "platform/ui"
+  ],
+  "repositoryPathPattern": "internal-git/{repo}"
+}
+```
+
+### Custom Git Protocol
+```json
+{
+  "url": "git://git.example.com:9418/",
+  "repos": [
+    "public/project1",
+    "public/project2"
+  ],
+  "repositoryPathPattern": "{base}/{repo}",
+  "exclude": [
+    {"pattern": ".*-backup$"},
+    {"name": "public/archive"}
+  ]
+}
+```
+
+### Local Repository Discovery
+```json
+{
+  "repos": ["src-serve-local"],
+  "root": "/path/to/local/repos",
+  "repositoryPathPattern": "local/{repo}"
+}
+```
+
+## Best Practices
+
+### Setup and Configuration
+- Test Git connectivity manually before configuring the code host
+- Use meaningful `repositoryPathPattern` to avoid naming conflicts
+- Start with a small set of repositories for initial testing
+- Verify repository paths match your Git hosting structure
+
+### Security
+- Use SSH keys for private repository access when possible
+- Store authentication tokens securely using environment variables
+- Implement proper access controls on the Git host side
+- Regularly audit repository access and permissions
+
+### Performance
+- Use exclude patterns to limit repository scope
+- Consider repository size when planning sync schedules
+- Monitor network performance for large repository sets
+- Plan for Git protocol limitations and timeouts
+
+### Maintenance
+- Keep repository lists updated with infrastructure changes
+- Monitor sync errors and connectivity issues
+- Regularly review exclude patterns and repository configurations
+- Plan for Git host migrations and URL changes
+
+### Protocol Considerations
+- HTTPS is recommended for most configurations
+- SSH requires additional key management but offers better security
+- Git protocol is efficient but less secure than HTTPS
+- Consider protocol-specific firewall and network requirements
+
+### Repository Organization
+- Use consistent naming patterns across repositories
+- Group related repositories using path prefixes
+- Document repository inclusion criteria
+- Consider using separate connections for different repository groups
+
+### Troubleshooting
+- Test Git clone operations manually using the same URLs
+- Verify network connectivity to Git host and required ports
+- Check authentication credentials and permissions
+- Review Git host logs for access and error information
diff --git a/docs/admin/code_hosts/phabricator.mdx b/docs/admin/code_hosts/phabricator.mdx
index 488be411e..14557ceaa 100644
--- a/docs/admin/code_hosts/phabricator.mdx
+++ b/docs/admin/code_hosts/phabricator.mdx
@@ -95,3 +95,117 @@ The Sourcegraph instance's site admin must [update the `corsOrigin` site config
 }
 ```
 {/* SCHEMA_SYNC_END: admin/code_hosts/phabricator.schema.json */}
+
+## Configuration Notes
+
+### Authentication Options
+- Phabricator supports optional Conduit API token authentication
+- Tokens are used to automatically discover available repositories
+- Manual repository configuration is possible without tokens
+
+### Repository Association
+- Repositories can be discovered via API token or configured manually
+- Manual configuration requires mapping Sourcegraph paths to Phabricator callsigns
+- Callsigns are case-sensitive and must match exactly
+
+### Integration Purpose
+- Phabricator connections provide outbound links from Sourcegraph to Phabricator
+- Native extension offers better integration than browser extensions
+- CORS configuration is required for native extension functionality
+
+## Security Considerations
+
+### API Token Management
+- Conduit API tokens provide read access to repository metadata
+- Store tokens securely using environment variables or secret management
+- Consider using dedicated Phabricator users for integration
+- Regularly audit token usage and permissions
+
+### Access Control
+- Phabricator repository permissions are not enforced by Sourcegraph
+- All configured repositories will be accessible to Sourcegraph users
+- Consider using dedicated Phabricator instances for integration
+
+### Network Security
+- Ensure Sourcegraph can access Phabricator server on configured ports
+- CORS configuration must allow Sourcegraph domain for native extension
+- HTTPS is recommended for secure API communication
+
+## Common Examples
+
+### API Token Configuration
+```json
+{
+  "url": "https://phabricator.example.com/",
+  "token": "api-abcdefghijklmnop"
+}
+```
+
+### Manual Repository Mapping
+```json
+{
+  "url": "https://phabricator.example.com/",
+  "repos": [
+    {
+      "path": "github.com/myorg/myrepo",
+      "callsign": "MR"
+    },
+    {
+      "path": "internal.git.company.com/platform/core",
+      "callsign": "CORE"
+    }
+  ]
+}
+```
+
+### Combined Configuration
+```json
+{
+  "url": "https://phabricator.example.com/",
+  "token": "api-abcdefghijklmnop",
+  "repos": [
+    {
+      "path": "custom.git.server.com/special/repo",
+      "callsign": "SPECIAL"
+    }
+  ]
+}
+```
+
+## Best Practices
+
+### Setup and Configuration
+- Use API tokens when possible for automatic repository discovery
+- Verify repository path mappings match Phabricator's normalized URIs
+- Test outbound links to ensure proper configuration
+- Document callsign mappings for manual configurations
+
+### Security
+- Use dedicated Phabricator users for API token generation
+- Implement proper CORS configuration for native extension
+- Regularly audit API token access and permissions
+- Consider Phabricator's authentication and authorization settings
+
+### Performance
+- Prefer API token configuration over manual repository mapping
+- Monitor API usage and respect Phabricator's rate limits
+- Consider caching strategies for large repository lists
+- Plan for Phabricator server maintenance windows
+
+### Maintenance
+- Keep CORS configurations updated with Sourcegraph URL changes
+- Monitor Phabricator server upgrades and API compatibility
+- Regularly review repository mappings for accuracy
+- Plan for Phabricator end-of-support migration
+
+### Integration Notes
+- Phabricator support is limited due to end-of-support announcement
+- Native extension is recommended over browser extension
+- Consider migration to actively supported code review platforms
+- Evaluate alternatives like GitHub, GitLab, or Bitbucket for new projects
+
+### Troubleshooting
+- Use Phabricator's Conduit API console to test token permissions
+- Verify normalized URI output matches Sourcegraph repository paths
+- Check CORS configuration for native extension issues
+- Review Phabricator server logs for API access errors
diff --git a/docs/admin/config/settings.mdx b/docs/admin/config/settings.mdx
index 2f1a2656a..abbeed4a5 100644
--- a/docs/admin/config/settings.mdx
+++ b/docs/admin/config/settings.mdx
@@ -150,6 +150,98 @@ Settings options and their default values are shown below.
 ```
 {/* SCHEMA_SYNC_END: admin/config/settings.schema.json */}
 
+## Configuration Notes
+
+### Search Settings
+- **`search.defaultPatternType`** - Controls default search behavior. Set to `"standard"` to disable keyword search if needed
+- **`search.contextLines`** - Default is 1 line of context above/below results. Increase for more context
+- **`search.displayLimit`** - Default 1500 results. Higher values may impact performance
+- **`search.includeArchived`** and **`search.includeForks`** - Control whether archived/forked repos appear in search by default
+
+### Code Intelligence
+- **`codeIntel.disableSearchBased`** - Set to true to only use precise code intelligence
+- **`codeIntel.mixPreciseAndSearchBasedReferences`** - Combines precise and search-based results for better coverage
+- **`basicCodeIntel.globalSearchesEnabled`** - May need to be disabled on large instances to prevent performance issues
+
+### UI Behavior
+- **`fileSidebarVisibleByDefault`** - Controls whether the file tree sidebar is open by default
+- **`history.preferAbsoluteTimestamps`** - Choose between relative ("5 days ago") or absolute timestamps
+- **`search.hideSuggestions`** - Disable search suggestions if they interfere with workflows
+
+## Security Considerations
+
+### Notifications & Alerts
+- **Notices** can be used to communicate security updates or maintenance windows
+- **`alerts.hideObservabilitySiteAlerts`** should be used carefully as it may hide important system alerts
+- Use **`dismissible: false`** for critical security notifications that users must see
+
+### Organization Settings
+- **`orgs.allMembersBatchChangesAdmin`** - Gives all org members admin rights to batch changes; use with caution
+- Consider the implications of allowing all org members to have admin privileges
+
+## Common Examples
+
+### Search-Optimized Configuration
+```json
+{
+  "search.defaultPatternType": "standard",
+  "search.contextLines": 3,
+  "search.displayLimit": 2000,
+  "search.includeArchived": false,
+  "search.includeForks": false,
+  "search.hideSuggestions": false,
+  "search.defaultCaseSensitive": false
+}
+```
+
+### Code Intelligence Configuration
+```json
+{
+  "codeIntel.disableSearchBased": false,
+  "codeIntel.mixPreciseAndSearchBasedReferences": true,
+  "basicCodeIntel.globalSearchesEnabled": true,
+  "basicCodeIntel.includeArchives": false,
+  "basicCodeIntel.includeForks": false
+}
+```
+
+### UI Customization
+```json
+{
+  "fileSidebarVisibleByDefault": true,
+  "history.preferAbsoluteTimestamps": false,
+  "history.defaultPageSize": 25,
+  "notices": [
+    {
+      "message": "Welcome to our code search platform!",
+      "location": "home",
+      "dismissible": true,
+      "variant": "info"
+    }
+  ]
+}
+```
+
+## Best Practices
+
+### Performance Optimization
+- Monitor search performance and adjust `search.displayLimit` accordingly
+- Consider disabling global searches (`basicCodeIntel.globalSearchesEnabled: false`) on large instances
+- Use search scopes to help users focus on relevant repositories
+- Set appropriate timeouts for unindexed searches
+
+### User Experience
+- Use notices strategically to communicate important information without overwhelming users
+- Configure search defaults that match your team's typical workflow
+- Consider enabling absolute timestamps for better auditability
+- Customize the file sidebar visibility based on your team's preferences
+
+### Code Intelligence
+- Start with mixed precise and search-based references for better coverage
+- Monitor performance impact of global code intelligence searches
+- Consider excluding archived repositories from code intelligence to improve relevance
+- Use precise-only mode for critical codebases where accuracy is paramount
+
 ## Additional details on settings
 
 ### Notices
diff --git a/docs/admin/config/site_config.mdx b/docs/admin/config/site_config.mdx
index 8ee7ec32d..3266b3539 100644
--- a/docs/admin/config/site_config.mdx
+++ b/docs/admin/config/site_config.mdx
@@ -937,6 +937,87 @@ 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
+
+### Core Settings
+- **`externalURL`** - This is the most important setting and must be configured for Sourcegraph to work correctly
+- **`auth.providers`** - Controls how users authenticate. The builtin provider with `allowSignup: false` means only the initial admin can invite other users
+- **`licenseKey`** - Required to activate Enterprise features. Contact Sourcegraph for a license
+
+### Performance & Scaling
+- **Repository Limits** - `maxReposToSearch` (deprecated, use `search.limits.maxRepos`) prevents resource exhaustion on large instances
+- **Git Operations** - `gitMaxConcurrentClones` and `gitMaxCodehostRequestsPerSecond` control git operation throttling
+- **Permissions Sync** - Multiple settings control how often and how many permissions jobs run concurrently
+
+### Security Considerations
+- **Token Security** - All access tokens (`executors.accessToken`, external service tokens) should contain at least 20 characters
+- **Session Management** - `auth.sessionExpiry` defaults to 90 days; consider shorter durations for sensitive environments
+- **Permission Enforcement** - `authz.enforceForSiteAdmins` ensures even site admins respect repository permissions
+- **Username Changes** - Set `auth.enableUsernameChanges: false` when using external auth to prevent privilege escalation
+
+## Common Examples
+
+### Basic Production Setup
+```json
+{
+  "externalURL": "https://sourcegraph.company.com/",
+  "auth.providers": [
+    {
+      "type": "saml",
+      "configID": "saml",
+      "displayName": "Company SSO"
+    }
+  ],
+  "corsOrigin": "https://gitlab.company.com/",
+  "email.address": "sourcegraph@company.com",
+  "email.smtp": {
+    "host": "smtp.company.com",
+    "port": 587,
+    "username": "sourcegraph@company.com",
+    "password": "smtp-password"
+  }
+}
+```
+
+### Development Instance
+```json
+{
+  "externalURL": "http://localhost:3080/",
+  "auth.providers": [
+    {
+      "type": "builtin",
+      "allowSignup": true
+    }
+  ],
+  "disableAutoGitUpdates": false,
+  "observability.tracing": {
+    "type": "opentelemetry",
+    "debug": true,
+    "sampling": "all"
+  }
+}
+```
+
+## Best Practices
+
+### Authentication & Authorization
+- Use external authentication providers (SAML, OIDC) rather than builtin auth for production
+- Configure repository permissions to match your organization's access control
+- Set appropriate session expiry times based on security requirements
+- Disable username changes when using external auth
+
+### Monitoring & Observability
+- Configure email settings for system notifications
+- Set up tracing for debugging performance issues
+- Use `observability.alerts` to route critical alerts to your team
+- Monitor git operation timeouts and adjust based on repository sizes
+
+### Resource Management
+- Set reasonable search limits to prevent resource exhaustion
+- Configure git operation concurrency based on your gitserver capacity
+- Use rate limiting for external service API calls
+- Set up proper cleanup intervals for background jobs
+
 ## 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..2c9a18680 100644
--- a/docs/admin/repo/perforce.mdx
+++ b/docs/admin/repo/perforce.mdx
@@ -267,6 +267,147 @@ With this setting, Sourcegraph will ignore any rules with a host other than `*`,
 }
 ```
 
+## Configuration Notes
+
+### Authentication Requirements
+- Perforce requires user credentials with appropriate permissions
+- Use `p4 login -p -a` to obtain ticket values for authentication
+- Service accounts should have "super" access level for permissions syncing
+
+### Repository Conversion
+- Perforce depots are converted to Git repositories using p4-fusion
+- Only "local" type depots are supported
+- Repository names follow the `repositoryPathPattern` configuration
+
+### Performance Considerations
+- p4-fusion client is strongly recommended over git-p4
+- Configure `fusionClient.lookAhead` for optimal performance
+- Large depot conversions may require significant time and resources
+
+## Security Considerations
+
+### Credential Management
+- Store P4PASSWD tickets securely using environment variables
+- Create dedicated service accounts for Sourcegraph integration
+- Use tickets that never expire for long-running integrations
+- Regularly audit P4 user permissions and access levels
+
+### Access Control
+- Repository-level permissions are enforced when `authorization` is configured
+- File-level permissions require experimental feature enablement
+- IP-based restrictions can be configured for enhanced security
+- Consider sub-repo permissions for granular access control
+
+### Network Security
+- Ensure Sourcegraph can access Perforce server on configured ports
+- Use SSL/TLS protocols (ssl:) for secure communication
+- Configure firewall rules for Perforce server access
+- Monitor P4 server logs for unusual access patterns
+
+## Common Examples
+
+### Basic p4-fusion Configuration
+```json
+{
+  "p4.port": "ssl:perforce.example.com:1666",
+  "p4.user": "sourcegraph-service",
+  "p4.passwd": "ticket-value-from-p4-login",
+  "depots": [
+    "//main/",
+    "//platform/ui/"
+  ],
+  "fusionClient": {
+    "enabled": true,
+    "lookAhead": 2000
+  }
+}
+```
+
+### Repository Permissions Setup
+```json
+{
+  "p4.port": "ssl:perforce.example.com:1666",
+  "p4.user": "sourcegraph-admin",
+  "p4.passwd": "admin-ticket-value",
+  "depots": ["//main/"],
+  "authorization": {},
+  "fusionClient": {
+    "enabled": true,
+    "lookAhead": 2000
+  }
+}
+```
+
+### File-Level Permissions Configuration
+```json
+{
+  "p4.port": "ssl:perforce.example.com:1666",
+  "p4.user": "sourcegraph-admin",
+  "p4.passwd": "admin-ticket-value",
+  "depots": ["//main/"],
+  "authorization": {
+    "subRepoPermissions": true
+  },
+  "fusionClient": {
+    "enabled": true,
+    "lookAhead": 2000
+  }
+}
+```
+
+### Custom Repository Path Pattern
+```json
+{
+  "p4.port": "tcp:internal-p4:1666",
+  "p4.user": "build-service",
+  "p4.passwd": "build-ticket",
+  "depots": [
+    "//products/app1/",
+    "//products/app2/"
+  ],
+  "repositoryPathPattern": "perforce/{depot}",
+  "maxChanges": 5000
+}
+```
+
+## Best Practices
+
+### Setup and Configuration
+- Use p4-fusion client for better performance than git-p4
+- Create dedicated Perforce users for Sourcegraph integration
+- Configure meaningful `repositoryPathPattern` to avoid conflicts
+- Test with small depots before configuring large-scale syncing
+
+### Security
+- Use SSL/TLS connections for secure communication
+- Implement proper P4 user permission structures
+- Enable file-level permissions for sensitive codebases
+- Regularly audit and rotate P4 tickets and credentials
+
+### Performance
+- Configure appropriate `lookAhead` values for p4-fusion
+- Use `maxChanges` to limit initial sync scope
+- Monitor changelist mapping performance for large depots
+- Plan for background computation overhead
+
+### Maintenance
+- Keep P4 tickets refreshed and valid
+- Monitor sync performance and error rates
+- Plan for depot renames and structural changes
+- Regularly review depot inclusion patterns
+
+### Permissions Management
+- Use sub-repo permissions for granular access control
+- Configure IP restrictions when network security is required
+- Plan for permissions sync delays with large user bases
+- Monitor user permission sync status and resolve issues
+
+### Migration and Integration
+- Plan changelist ID mapping for URL compatibility
+- Consider Batch Changes limitations with file-level permissions
+- Test experimental features in non-production environments
+- Document custom configuration requirements for your environment
+
 ## Known issues and limitations
 
 We are actively working to significantly improve Sourcegraph's Perforce support. Please [contact us](https://help.sourcegraph.com/hc/en-us/requests/new) to help us prioritize any specific improvements you'd like to see.