Resolving GitHub Permission Denied Error: Public Key Authentication and SSH Configuration

Analysis of GitHub Public Key Authentication Errors

When performing operations on remote repositories with Git, developers often encounter the Permission denied (publickey) error message. This indicates that the GitHub server cannot verify the user's identity, typically due to improper or missing SSH key configuration. SSH key pairs are the core mechanism for GitHub authentication, consisting of a private key stored locally and a public key that must be uploaded to the GitHub account.

SSH Key Generation and Addition Process

First, generate an SSH key pair locally. Open the terminal and execute the ssh-keygen -t rsa -b 4096 -C "your_email@example.com" command. The system will prompt for the key file path and passphrase, with the default path being ~/.ssh/id_rsa. After generation, use cat ~/.ssh/id_rsa.pub to view the public key content and copy the entire text.

Next, log in to the GitHub website, click on your profile picture in the upper-right corner, and select Settings. Find the SSH and GPG keys option in the left menu, click it, and then select the New SSH key button. Enter a recognizable title in the title field, paste the copied public key content into the key field, and finally click Add SSH key to complete the addition.

SSH Agent Management and Connection Testing

To ensure the SSH key remains available during the session, start the SSH agent and add the private key. Execute eval "$(ssh-agent -s)" to start the agent, then use ssh-add ~/.ssh/id_rsa to add the private key. If the system prompts for a passphrase, enter the one set during key generation.

After completing these steps, test the SSH connection. Run ssh -T git@github.com; if it returns Hi username! You've successfully authenticated, but GitHub does not provide shell access., authentication is successful. At this point, re-execute previous Git operations, such as git push -u origin master, and the error should be resolved.

SSH Configuration Adjustments for Network Environments

In some network environments, the standard SSH port (22) may be blocked by firewalls, causing connection timeouts. In this case, try connecting using an alternative port. Execute ssh -T -p 443 git@ssh.github.com; if authentication succeeds, port 443 is available.

To permanently resolve this issue, modify the SSH configuration file. Open the ~/.ssh/config file with a text editor and add the following content:

Host github.com
  Hostname ssh.github.com
  Port 443

After saving the file, test the connection again: ssh -T git@github.com. This connection will use the configured Hostname and Port, typically establishing successfully. This configuration ensures reliable connectivity to GitHub across different network environments.

Troubleshooting and Summary

If the problem persists after following these steps, check common issues: ensure the public key was copied correctly to GitHub without extra spaces or line breaks; verify that the private key has been added to the SSH agent; confirm that the remote repository URL uses the SSH protocol (e.g., git@github.com:username/repo.git), not HTTPS. Through systematic SSH key management and network configuration, developers can thoroughly resolve GitHub permission denied errors and perform version control operations smoothly.