github sync

github sync allows teams to share port-forward configurations through github repositories, enabling version control and automatic distribution of configuration changes across team members.

when github sync matters

github sync becomes useful when teams need consistent port-forward configurations across multiple developers. this comes up especially in microservices environments where the same set of forwards (databases, APIs, message queues) needs to work consistently for everyone.

without centralized configuration sharing, teams often pass JSON files manually, leading to configuration drift when some developers have outdated or modified setups. github sync keeps everyone's configurations synchronized automatically.

this feature currently works only in the desktop interface, not the terminal version.

how github sync works

the basic idea is storing configuration JSON files in a github repository and having kftray periodically check for updates. when someone changes the shared configuration, other team members automatically receive the updates on their next sync.

the workflow looks like this: someone sets up a github repository with configuration files, team members configure github sync in their kftray installation, and changes propagate automatically based on the configured sync interval.

setting up repository-based sharing

start by creating a github repository for configuration storage. the repository structure can be simple:

team-kftray-configs/
├── README.md
├── development.json
├── staging.json
└── production.json

each JSON file contains an array of configurations for that environment:

[
  {
    "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"
  }
]

authentication and access control

github sync requires a Personal Access Token for repository access. generate this token in GitHub's developer settings with appropriate scope permissions.

for private repositories, the token needs repo scope for full repository access. for public repositories, public_repo scope is sufficient for reading configuration files.

configure the token in kftray through Settings > GitHub Sync, along with the repository URL and desired sync interval.

sync behavior and conflict handling

kftray checks the repository periodically based on the configured interval (typically every few minutes). when changes are detected, the tool downloads the new configuration and merges it with local settings.

conflict resolution happens automatically: repository configurations take precedence over local changes for synchronized files. local-only configurations remain unaffected.

manual sync triggers are available when immediate updates are needed, bypassing the periodic check interval.

the sync process handles network failures gracefully with retry logic and reports errors through the application interface when github access fails.

team workflow integration

adding new services

when someone adds a new microservice to the development environment, they update the shared configuration file:

# Clone the config repository
git clone https://github.com/team/kftray-configs.git
cd kftray-configs

# Edit development.json to add the new service
# Commit and push changes
git add development.json
git commit -m "Add notification service forwarding"
git push

team members receive the update automatically on their next sync, ensuring everyone can access the new service without manual configuration.

environment-specific configurations

teams often need different configurations for different environments. separate JSON files handle this:

development.json for local development forwards, staging.json for staging environment access, and production.json for production debugging access (with appropriate security controls).

developers can sync multiple environment configurations and enable the ones relevant to their current work.

configuration reviews and changes

using pull requests for configuration changes provides review and approval workflow:

# Create feature branch for config changes
git checkout -b add-redis-forwarding

# Update configuration files
# Create pull request for review
# Merge after approval

this prevents accidental configuration changes and provides visibility into what services are being accessed by the team.

security considerations and limitations

access token security

personal access tokens have significant github permissions and should be treated as sensitive credentials. rotate tokens regularly and revoke unused tokens to minimize security exposure.

avoid sharing tokens between team members -- each developer should generate their own token with minimal required permissions.

repository access control

private repositories provide better security for sensitive configuration information. public repositories work for open-source projects but expose service names, namespaces, and port assignments.

repository access controls determine who can read and modify shared configurations. use github's team permissions to restrict access appropriately.

configuration content security

configuration files may contain sensitive information like service names, namespaces, and internal network topology. review what information gets stored in shared repositories.

avoid including sensitive connection details (passwords, API keys) in configuration files. these should remain in local environment variables or separate secret management systems.

troubleshooting sync problems

authentication failures

when sync fails with authentication errors, verify that the access token is valid and has appropriate permissions. tokens can expire or be revoked, breaking sync functionality.

check that the repository URL is correct and accessible with the provided token. private repositories require read access through the token.

network and connectivity issues

sync problems often stem from network connectivity issues or github API rate limiting. the application retries failed requests automatically but may need manual retry for persistent problems.

corporate networks may block github API access or require proxy configuration for external connectivity.

conflict resolution problems

when local configurations conflict with repository versions, the repository takes precedence. local changes get overwritten, which may not always be desired behavior.

back up local configurations before enabling github sync to preserve custom settings that shouldn't be shared with the team.

alternative sharing approaches

github sync works well for teams already using github workflows, but isn't the only configuration sharing option. direct JSON file export/import provides simpler sharing for small teams or one-time configuration distribution.

version control systems other than github (GitLab, Bitbucket) aren't currently supported but serve similar use cases with manual file sharing.

teams with complex configuration requirements might prefer custom configuration management systems that integrate with their existing infrastructure and security policies.

when to avoid github sync

simple, single-developer setups don't benefit from the complexity of repository-based configuration sharing. the overhead isn't worth it for individual development work.

teams with strict security requirements may find repository-based sharing incompatible with their policies around external service access or credential management.

highly dynamic environments where configurations change frequently may find the sync interval limiting or the repository workflow too slow for rapid iteration.