Skip to content

Revert "Make a section for the tribal knowledge contained in the schema files" #1232

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 1, 2025
Merged

Revert "Make a section for the tribal knowledge contained in the schema files" #1232

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
125 changes: 0 additions & 125 deletions docs/admin/code_hosts/aws_codecommit.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,131 +114,6 @@ 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.
Expand Down
105 changes: 0 additions & 105 deletions docs/admin/code_hosts/azuredevops.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -129,111 +129,6 @@ 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.
Expand Down
Loading