GitKraken Internal SSH Store or System ssh-agent for Headless Production Hosts

Direct Answer

Use the system ssh-agent. GitKraken's internal SSH store depends on an unlocked OS keychain (macOS Keychain, Windows Credential Manager, GNOME Keyring/KWallet), which is unavailable without an interactive graphical login. The system ssh-agent runs independently of the user session and works on headless hosts when started and loaded via CLI.

Why the Internal Store Fails on Headless Hosts

• GitKraken encrypts private keys in its internal store and delegates decryption to the OS keychain daemon.
• On Linux, the keyring daemon (gnome-keyring-daemon, kwalletd) starts with the graphical session; no session = no daemon = locked store.
• On macOS, the login keychain unlocks only when the user logs in interactively; launchd agents for background users keep the keychain locked.
• On Windows, Credential Manager requires the user's logon session; service accounts or SSH logins do not unlock it.

Why System ssh-agent Works

• ssh-agent is a standalone process that holds decrypted keys in memory.
• It can be started from systemd, launchd, rc.local, or a shell profile before GitKraken launches.
• GitKraken's Preferences → SSH → Use local SSH agent setting tells it to query SSH_AUTH_SOCK instead of its internal store.
• No browser, no GUI, no keychain unlock required.

Required Steps (Linux/macOS Example)

1. Start the agent and persist its socket:

   eval "$(ssh-agent -s)"
   echo "export SSH_AUTH_SOCK=$SSH_AUTH_SOCK" >> ~/.ssh/agent.env
   echo "export SSH_AGENT_PID=$SSH_AGENT_PID" >> ~/.ssh/agent.env

2. Add the key (passphrase prompted once, then cached):

   ssh-add ~/.ssh/id_ed25519

3. Ensure the environment variables are sourced by the process that launches GitKraken (systemd service, docker entrypoint, CI script, etc.).
4. In GitKraken: Preferences → SSH → Use local SSH agent (enable).
5. Verify: ssh-add -l shows the key; GitKraken Fetch/Push succeeds.

OS-Specific Factors That Change the Recommendation

OS	Keychain Behavior	ssh-agent Viability
Linux (headless)	No keyring daemon by default	Only viable path
macOS (background user)	Login keychain stays locked	Works if agent started in user's launchd context
Windows (service/SSH)	Credential Manager inaccessible	Works via OpenSSH service or npiperelay to WSL agent

GitKraken Version Note

Versions ≥ 8.x surface "Use local SSH agent" clearly in Preferences → SSH. Older versions may require editing ~/.gitkraken/config.json manually ("useLocalAgent": true). If the setting is missing, upgrade GitKraken.

One Diagnostic Detail Needed

Which operating system and launch method (systemd service, Docker, SSH session, CI runner) runs GitKraken on this host? The exact ssh-agent startup procedure differs (systemd user service vs. launchd vs. Windows OpenSSH service), and confirming the environment lets me give the precise startup snippet.