Diagnosis and Solutions for SSH Key Connection Failures to GitHub

Problem Background and Symptom Analysis

During SSH connections to GitHub, developers frequently encounter the "Permission denied (publickey)" error, even after following standard procedures for generating SSH keys and adding them to their GitHub accounts. The provided debug logs reveal that while the SSH client successfully establishes a connection with GitHub servers, authentication fails at the final stage.

Critical information from the debug logs includes: debug1: Authentications that can continue: publickey and debug1: Offering RSA public key: /home/trusktr/.ssh/id_rsa, indicating that the server only accepts public key authentication, but the client's provided keys are not being accepted. Further analysis shows the SSH client sequentially attempts multiple key files: id_rsa, trusktr@rocketship, id_dsa, and id_ecdsa, with all attempts failing.

Core Issue Diagnosis

The root cause of the problem lies in the missing correct username configuration in the SSH connection command. When executing ssh github.com, the SSH client defaults to using the current system username for connection, while GitHub's SSH service requires the dedicated git user.

The correct connection command should be: ssh -T git@github.com. The -T parameter indicates no pseudo-terminal allocation, which is suitable for Git operations. git@github.com follows the standard SSH URI syntax format, where git is the specialized username for GitHub's SSH service.

To verify if the SSH connection is working properly, use the following test command:

ssh -T git@github.com

If configured correctly, GitHub will return a success message similar to "Hi username! You've successfully authenticated".

SSH Configuration Optimization

To avoid needing to specify the username with every connection, create an SSH configuration file to simplify operations. Add the following configuration to ~/.ssh/config:

Host github.com
    User git
    Port 22
    Hostname github.com
    IdentityFile ~/.ssh/id_rsa
    TCPKeepAlive yes
    IdentitiesOnly yes

The parameters in this configuration file have the following meanings:

• Host github.com: Specifies the hostname to which the configuration applies
• User git: Sets the username to use when connecting
• IdentityFile ~/.ssh/id_rsa: Specifies the path to the private key file
• IdentitiesOnly yes: Ensures only the specified identity files are used

After configuration, you can directly use the ssh github.com command, and the system will automatically apply the settings from the configuration file.

Git Remote Repository URL Configuration

Another common issue is incorrect Git remote repository URL configuration. If the repository uses HTTPS URLs instead of SSH URLs, Git operations will still fail even with properly configured SSH keys.

Check the current remote repository configuration:

git remote -v

If the output shows HTTPS URLs:

origin  https://github.com/username/repository.git (fetch)
origin  https://github.com/username/repository.git (push)

Change them to SSH URLs:

git remote set-url origin git@github.com:username/repository.git

Or use the full SSH protocol format:

git remote set-url origin ssh://git@github.com/username/repository.git

The git remote set-url command is the safe method for modifying remote repository URLs, automatically updating the corresponding configuration in the .git/config file.

SSH Key Management and Agent

If the SSH private key has a passphrase, you need to enter it each time the key is used. To simplify this process, use the SSH agent to manage keys.

On Linux and Windows systems, use the following command to add the key to the SSH agent:

ssh-add ~/.ssh/id_rsa

On macOS systems, use:

ssh-add -K ~/.ssh/id_rsa

Or the newer command:

ssh-add --apple-use-keychain ~/.ssh/id_rsa

The SSH agent runs in the background, automatically providing key authentication without requiring repeated passphrase entry.

Troubleshooting Workflow Summary

When encountering SSH connection failures to GitHub, follow this systematic troubleshooting process:

1. Test basic SSH connection using ssh -T git@github.com
2. Check if the ~/.ssh/config file is properly configured
3. Verify if Git remote repository URLs are in SSH format
4. Confirm SSH keys are correctly added to the GitHub account
5. Check if the SSH agent is running properly and has loaded the keys
6. Use ssh -vvv git@github.com to obtain detailed debugging information

This systematic approach helps quickly identify and resolve most SSH connection issues.

Advanced Configuration and Best Practices

For scenarios requiring management of multiple GitHub accounts or using different keys, implement this through SSH configuration file Host aliases:

Host github-work
    Hostname github.com
    User git
    IdentityFile ~/.ssh/id_work_rsa

Host github-personal
    Hostname github.com
    User git
    IdentityFile ~/.ssh/id_personal_rsa

Usage would correspond to:

git clone git@github-work:company/project.git
git clone git@github-personal:username/project.git

This configuration approach maintains security while providing operational flexibility.