Skip to content

User Guide

Welcome to the GitBridge User Guide. This comprehensive guide will help you understand and use all features of GitBridge effectively.

What You'll Learn

This guide covers everything from basic usage to advanced configurations:

  • Different synchronization methods and when to use them
  • Configuration options and best practices
  • Authentication and security setup
  • Corporate environment configurations
  • Performance optimization techniques
  • Troubleshooting common issues

Guide Sections

Sync Methods

Learn about the two synchronization methods (API and Browser) and when to use each one.

Configuration

Detailed guide to configuring GitBridge using YAML files, environment variables, and command-line options.

Authentication

Set up authentication for both API and browser methods, including token management and security best practices.

Incremental Sync

Understand how incremental synchronization works and how to optimize sync performance.

Branch Management

Learn how to sync specific branches, tags, or commits from your repository.

Corporate Setup

Configure GitBridge for corporate environments with proxies, PAC scripts, and custom certificates.

Proxy Configuration

Detailed guide to configuring various proxy types including HTTP, HTTPS, SOCKS, and PAC scripts.

SSL Certificates

Handle custom SSL certificates and certificate verification in restricted environments.

Quick Start Examples

Basic Synchronization

Sync a public repository:

Bash
1
gitbridge sync --repo https://github.com/user/repo --local ~/projects/repo

Authenticated Sync

Sync a private repository with authentication:

Bash
1
2
3
4
5
6
7
8
# Using environment variable
export GITHUB_TOKEN=your_token_here
gitbridge sync --repo https://github.com/user/private-repo --local ~/projects/repo

# Or directly in command
gitbridge sync --repo https://github.com/user/private-repo \
             --local ~/projects/repo \
             --token your_token_here

Corporate Environment

Sync in a corporate environment with auto-detection:

Bash
1
2
3
4
5
6
7
# Windows with auto-detection
gitbridge sync --config config.yaml --auto-proxy --auto-cert

# Manual proxy configuration
gitbridge sync --repo https://github.com/user/repo \
             --local ~/projects/repo \
             --proxy http://proxy.company.com:8080

Using Configuration File

Create a config.yaml file:

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
repository:
  url: https://github.com/username/repo
  ref: main

local:
  path: ~/projects/repo

auth:
  token: ${GITHUB_TOKEN}

sync:
  method: api
  incremental: true

network:
  auto_proxy: true
  auto_cert: true

Then run:

Bash
1
gitbridge sync --config config.yaml

Best Practices

1. Use Configuration Files

For repeated syncs, use a configuration file instead of command-line arguments:

  • Easier to manage complex configurations
  • Supports environment variable expansion
  • Can be version controlled (exclude sensitive data)

2. Enable Incremental Sync

Always use incremental sync for better performance:

YAML
1
2
sync:
  incremental: true

This only downloads changed files after the initial sync.

3. Set Up Authentication Properly

  • Use environment variables for tokens
  • Never commit tokens to version control
  • Use read-only tokens when possible
  • Rotate tokens regularly

4. Configure for Your Environment

  • Use --auto-proxy and --auto-cert on Windows
  • Configure specific proxy settings if auto-detection fails
  • Test connectivity with gitbridge status before syncing

5. Monitor Sync Operations

  • Use verbose mode (-v) for debugging
  • Check logs for any warnings or errors
  • Monitor sync statistics for performance

Common Use Cases

Continuous Integration

Sync repositories in CI/CD pipelines:

Bash
1
2
# In your CI script
gitbridge sync --repo $REPO_URL --local ./source --token $CI_TOKEN

Backup Solution

Create regular backups of repositories:

Bash
1
2
# Cron job for daily backup
0 2 * * * gitbridge sync --config /path/to/backup-config.yaml

Development Environment

Keep local copies synchronized:

Bash
1
2
3
4
# Sync multiple repositories
for repo in repo1 repo2 repo3; do
    gitbridge sync --config configs/$repo.yaml
done

Performance Tips

  1. Use API method when possible - It's faster and more efficient
  2. Enable parallel downloads - For large repositories
  3. Configure appropriate timeouts - Based on your network speed
  4. Use incremental sync - Avoid re-downloading unchanged files
  5. Exclude unnecessary files - Use ignore patterns for large binaries

Security Considerations

  1. Token Security
  2. Use minimal required permissions
  3. Store tokens securely (environment variables, secret managers)

  4. Rotate tokens regularly

  5. Network Security

  6. Verify SSL certificates
  7. Use secure proxy configurations

  8. Monitor network traffic

  9. Local Security

  10. Secure local repository copies
  11. Set appropriate file permissions
  12. Clean up temporary files

Getting Help

If you encounter issues:

  1. Check the Troubleshooting Guide
  2. Run with verbose mode (-v) for detailed output
  3. Check the GitHub Issues
  4. Contact support if needed

Next Steps