Diagnosing SSH Authentication Failures in Sourcetree

Problem Overview

When Sourcetree can’t pull or push to a remote Git repository, the most common culprit is an SSH authentication error. Typical messages include Permission denied (publickey) or a generic timeout. This guide walks you through a systematic diagnosis, from local key setup to network checks, and provides concrete fixes tied to each finding.

Cause & Diagnostic Table

Possible Cause	Diagnostic Check	What to Look For
SSH key missing on your machine	Run ssh-add -l	No keys listed, or key not matching the one on the remote host
Private key not added to remote host (e.g., GitHub)	Open the remote host’s SSH key settings	Key is absent or mismatched
SSH agent not running or key not loaded	Check ssh-agent status	Agent stopped or key not added
Sourcetree using HTTPS instead of SSH	Inspect remote URL in Sourcetree	URL starts with https:// instead of git@
Network firewall blocks outbound SSH (port 22)	Test SSH from terminal	Connection times out or is refused

Ordered Checks & Fixes

1. Verify the Remote URL Scheme
   • In Sourcetree, open the repository settings and locate the Remote section.
   • Ensure the URL begins with [contact removed]:repo.git or ssh://[contact removed]/repo.git.
   • If it starts with https://, edit it to use SSH.
2. Confirm the SSH Key Exists Locally
   • Open a terminal and run:

     ls ~/.ssh/id_rsa ~/.ssh/id_rsa.pub

   • If the files are missing, generate a new key pair:

     ssh-keygen -t ed25519 -C "[contact removed]" -f ~/.ssh/id_ed25519

     (replace ed25519 with rsa if required).
   • Keep the private key in a secure location and protect it with a passphrase.
3. Ensure the Key Is Loaded into the SSH Agent
   • Start the agent if not already running:

     eval "$(ssh-agent -s)"
     ssh-add ~/.ssh/id_ed25519

   • Validate with:

     ssh-add -l

     – you should see your key listed.
   • In Sourcetree, go to Tools → Options → Git and confirm that “Use system SSH” is checked, so Sourcetree will use the same agent.
4. Check the Remote Host’s Authorized Keys
   • Copy the public key to the clipboard:

     cat ~/.ssh/id_ed25519.pub | pbcopy

     (use xclip or clip on Linux/Windows).
   • Log into the remote service (GitHub, GitLab, Bitbucket) and add the key under SSH keys.
   • Verify the key’s fingerprint matches the one displayed by ssh-keygen -lf ~/.ssh/id_ed25519.pub.
5. Test SSH Outside Sourcetree
   • Run:

     ssh -T [contact removed]

     (replace github.com with your host).
   • A successful handshake returns a welcome message; failure indicates a problem outside Sourcetree.
6. Inspect Sourcetree’s Log for Specific Errors
   • Navigate to View → Show Log and search for ssh or Permission denied.
   • Note the exact error string; it can point to host key verification failures or key mismatches.
7. Network Firewall Check
   • From the terminal, run:

     telnet github.com 22

     (or use nc -vz github.com 22).
   • If the connection fails, contact your network administrator to open outbound port 22.
8. Re‑add the Repository in Sourcetree
   • Remove the remote from the repository settings and re‑add it using the SSH URL.
   • Force a pull or push to trigger authentication again.

Escalation Criteria

• After completing all checks, if the error persists and ssh -T succeeds from the terminal, the problem is likely within Sourcetree’s configuration. Re‑installing Sourcetree or resetting its Git settings can help.
• If ssh -T also fails, the issue lies outside Sourcetree. Escalate to your network or system administrator, providing the error logs and the steps taken.
• For persistent host key verification errors, verify that your local ~/.ssh/known_hosts file contains the correct entry for the host. Remove stale entries with ssh-keygen -R github.com and retry.

Concrete Example: Configuring a Multi‑Host SSH Setup

# ~/.ssh/config
Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes

Host gitlab.com
  HostName gitlab.com
  User git
  IdentityFile ~/.ssh/id_rsa
  IdentitiesOnly yes

With this configuration, Sourcetree will automatically use the correct key for each host, provided the agent is running.

Limitations & Practical Checks

• Some hosting providers block port 22 and require using ssh://[contact removed]:443. Adjust the remote URL accordingly.
• If you use a corporate VPN, ensure that the VPN allows SSH traffic.
• Always keep a backup of your private key. Losing it will require generating a new pair and updating all remote hosts.

Takeaway

Authentication failures in Sourcetree are almost always due to missing or mis‑configured SSH keys, an inactive agent, or a wrong remote URL. By following the ordered checks above, you can pinpoint the exact cause and resolve it without unnecessary trial and error.