GitHub Sync
Share port-forward configurations across a team through a GitHub repository.
GitHub sync pulls your team's port-forward configs from a shared repository. Commit the JSON once and everyone gets new configs and changes on the next sync.
Setup
Create a configuration repository
Export your configs to a JSON file (see import and export), then commit it to a GitHub repository:
mkdir kftray-configs
cd kftray-configs
git init
# Create configuration files
cat > production.json <<EOF
[
{
"alias": "Production API",
"service": "api-gateway",
"namespace": "production",
"local_port": 8080,
"remote_port": 80,
"context": "prod-cluster",
"workload_type": "service",
"protocol": "tcp"
},
{
"alias": "Production Database",
"service": "postgres",
"namespace": "databases",
"local_port": 5432,
"remote_port": 5432,
"context": "prod-cluster",
"workload_type": "service",
"protocol": "tcp"
}
]
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 holds an array of configuration objects. You can organize files by environment, team or service group and sync several of them at once.
kftray uses the repository's default branch. There's no branch setting.
Configure sync
Select the GitHub icon (Configure Git Sync) in the footer.
Enter the URL of your repository, for example https://github.com/your-org/kftray-configs.
Enter the path to the JSON config file. If your configs are split across several files, use the + button to add more paths.
For a private repository, enter a personal access token. See Authentication.
Set the polling interval, the time between automatic syncs.
Save. kftray syncs with the repository and imports new configs and changes.
| Option | Detail |
|---|---|
| Polling interval | A slider from 0 to 120 minutes in steps of 5. The default is 60 minutes. 0 turns automatic polling off |
| Flush existing configs before sync | Off by default. When on, kftray deletes all your local configs before it imports |
While Git credentials are configured, Import Local File in the footer menu is disabled.
Authentication
Public repositories need no token. For a private repository, GitHub sync needs a personal access token that can read it. A classic token with the repo scope works.
Create a token at https://github.com/settings/tokens:
Click "Generate new token (classic)".
Name it "kftray sync".
Set an expiration that fits your security policy.
Select the repo scope.
Click "Generate token".
Copy the token right away, because GitHub won't show it again.
The desktop app saves the token, with the other sync settings, in the system keyring (Keychain on macOS). kftray doesn't store credentials in any local file.
Token security
A personal access token grants access to every repository in its scope. Store tokens securely and rotate them regularly. Never commit tokens to version control or share them in chat.
Sync behavior
Periodic checks
The desktop app syncs at the polling interval, 60 minutes by default. Each sync updates your configs one at a time:
kftray matches repository configs to local configs by context, namespace, workload type, protocol and target. The target is a service, pod selector or proxy address.
When a config has a non-zero local port, the local and remote ports must match too. For expose configs, kftray matches by alias and local port.
A match is updated with the repository's values and keeps its ID. If the repository's alias is blank or its local port is missing or 0, kftray keeps the old alias or local port.
A config with no match is added.
kftray doesn't delete local configs that are missing from the repository, unless Flush existing configs before sync is on.
Conflict resolution
The repository wins. If you change a synced configuration locally, the next sync overwrites it with the repository version.
To keep local changes:
Turn polling off by setting the interval to 0.
Export your local configurations.
Merge your changes into the repository and push to GitHub.
Turn sync back on.
Manual trigger
To fetch the latest configs before the next scheduled check, click the Sync button in the footer. Hover over it to see the repository, paths, authentication, interval and the last and next sync times. The button is disabled while a sync runs or when no credentials are configured. A scheduled sync is skipped while another one is running.