GitHub Sync
Share and synchronize port-forward configurations across teams using GitHub repositories.
GitHub sync lets you share port-forward configurations through a GitHub repository, keeping your team's setups consistent and up to date.
Setup
Create a configuration repository
Create a new GitHub repository to store your team's port-forward configurations:
mkdir kftray-configs
cd kftray-configs
git init
# Create configuration files
cat > production.json <<EOF
[
{
"service": "api-gateway",
"namespace": "production",
"local_port": 8080,
"remote_port": 80,
"context": "prod-cluster",
"alias": "Production API"
},
{
"service": "postgres",
"namespace": "databases",
"local_port": 5432,
"remote_port": 5432,
"context": "prod-cluster",
"alias": "Production Database"
}
]
EOF
git add production.json
git commit -m "Add production configurations"
git remote add origin [email protected]:your-org/kftray-configs.git
git push -u origin mainRepository structure
Each JSON file contains an array of configuration objects. Organize files by environment, team, or service group.
Configure sync
Open kftray desktop interface.
Go to Settings → GitHub Sync.
Enter repository URL: https://github.com/your-org/kftray-configs
Enter branch name: main
Provide Personal Access Token (see authentication below).
Click "Enable Sync".
kftray immediately fetches configurations and checks for updates every 5 minutes.
Pass the GitHub repository URL and config file path when launching kftui:
kftui --github-url https://github.com/your-org/kftray-configs --configs-path env/production.jsonAdd --save to persist the imported configurations to the local database:
kftui --github-url https://github.com/your-org/kftray-configs --configs-path env/production.json --saveFor private repositories, set the GITHUB_TOKEN environment variable before launching.
Authentication
GitHub sync requires a Personal Access Token with repo scope for private repositories or public_repo scope for public repositories.
Create a token at https://github.com/settings/tokens:
Click "Generate new token (classic)".
Name: "kftray sync".
Expiration: Choose based on your security policy.
Scopes: Select repo (or public_repo for public repositories only).
Click "Generate token".
Copy the token immediately (you won't see it again).
Token security
Personal Access Tokens grant access to all repositories in the selected scope. Store tokens securely and rotate them regularly. Never commit tokens to version control or share them in chat.
Sync behavior
Periodic checks
kftray checks the repository for updates every 5 minutes. When changes are detected:
New configurations are added to your local database.
Modified configurations update existing entries (matched by service + namespace + context).
Deleted configurations are removed from your local database.
Conflict resolution
Repository configurations always win. If you modify a synced configuration locally, the next sync overwrites your changes with the repository version.
To preserve local changes:
Disable GitHub sync temporarily.
Export your local configurations.
Merge changes into the repository.
Push to GitHub.
Re-enable sync.
Manual trigger
Force an immediate sync check:
Go to Settings → GitHub Sync.
Click "Sync Now".
This bypasses the 5-minute interval and fetches the latest configurations immediately.