GitHub Sync

kftray support synchronizing port forward configurations with GitHub repositories, enabling team collaboration and configuration version control.

Currently available in KFtray GUI. Coming soon to KFtui.

Setup GitHub Sync

  1. Create Configuration Repository
    • Create a new GitHub repository
    • Add your configuration JSON file
    • Structure example:
      repo/
      โ””โ”€โ”€ configs/
          โ””โ”€โ”€ port-forwards.json
      
  2. Configure GitHub Access
    • Generate a GitHub Personal Access Token
    • Token needs repo scope for private repositories
    • Token only needs public_repo for public repositories
  3. Enable Sync in KFtray
    • Open Settings
    • Navigate to GitHub Sync
    • Enter repository URL
    • Provide access token
    • Set sync interval

Configuration Format

Example repository configuration:

[
  {
    "service": "frontend",
    "namespace": "default",
    "local_port": 3000,
    "remote_port": 80,
    "protocol": "tcp",
    "alias": "web"
  },
  {
    "service": "backend",
    "namespace": "default",
    "local_port": 8080,
    "remote_port": 8080,
    "protocol": "tcp",
    "alias": "api"
  }
]

Sync Features

  • Automatic periodic synchronization
  • Manual sync trigger
  • Conflict resolution
  • Error handling and retry
  • Secure credential storage

Best Practices

  1. Repository Organization
    • Use clear file naming
    • Organize by environment/team
    • Include documentation
    • Version control changes
  2. Security
    • Use private repositories for sensitive configs
    • Rotate access tokens regularly
    • Review repository access
  3. Team Collaboration
    • Document configuration changes
    • Use pull requests for updates
    • Review changes before merging

Troubleshooting

Common issues and solutions:

Authentication Failed

  • Verify token permissions
  • Check token expiration
  • Confirm repository access

Sync Conflicts

  • Pull latest changes
  • Resolve conflicts locally
  • Push resolved configurations

Network Issues

  • Check internet connectivity
  • Verify GitHub API access
  • Review proxy settings

Example Workflows

Team Configuration Sharing

# Export current configurations
kftray export configs.json

# Commit to repository
git add configs.json
git commit -m "Update port forward configurations"
git push

Importing Team Configurations

  1. Configure GitHub sync
  2. Set sync interval
  3. Configurations automatically update

Security Notes

  • Store tokens securely
  • Avoid sharing tokens
  • Review synchronized configurations
  • Monitor repository access