Resolving GitHub SSH Public Key Authentication Failure: Permission Denied (Publickey) Error

SSH Public Key Authentication Principles and Error Analysis

When using Git for remote repository operations, the SSH (Secure Shell) protocol offers a secure authentication mechanism. Upon executing the git push -u origin master command, Git attempts to connect to GitHub servers via SSH. The "Permission denied (publickey)" error typically indicates SSH authentication failure, which may stem from:未生成 SSH key pairs, public keys not correctly added to GitHub accounts, misconfigured key paths, or inactive SSH agents. Understanding this mechanism is the first step toward resolution.

Generating SSH Key Pairs

To resolve this error, start by generating an SSH key pair. GitHub recommends using the Ed25519 algorithm for enhanced security and performance. Run the following command in the terminal:

ssh-keygen -t ed25519 -C "your_email@example.com"

This command generates a key pair: a private key (default saved at ~/.ssh/id_ed25519) and a public key (default saved at ~/.ssh/id_ed25519.pub). During generation, you will be prompted for a passphrase for added security, but it can be left blank for simplicity. For systems that do not support Ed25519, use the RSA algorithm:

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

Ensure to replace your_email@example.com with your actual email address to help identify the key.

Adding Public Key to GitHub Account

After generating the key pair, add the public key to your GitHub account. First, copy the public key content. On Linux or macOS, use cat ~/.ssh/id_ed25519.pub; on Windows, open the file with a text editor. Then, log into GitHub, navigate to Settings > SSH and GPG keys > New SSH key, paste the public key into the "Key" field, and add a descriptive title. Upon saving, GitHub will associate the public key with your account.

Configuring SSH Agent and Custom Key Paths

In some cases, errors may persist even after generating keys and adding them to GitHub. This could be due to an inactive SSH agent or misconfigured key paths. Start the SSH agent and add the private key:

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

If keys are stored in non-default locations, configure the SSH config file. Edit or create ~/.ssh/config and add:

Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/custom_key

Replace ~/.ssh/custom_key with the actual path to your private key. Note that the User field must be set to git, as this is the standard username for GitHub SSH connections.

Debugging and Verification

To diagnose issues, use the ssh -vT git@github.com command for detailed debugging. This outputs connection process details, helping identify specific causes of authentication failure. For example, if the output shows "Authentication succeeded," SSH configuration is correct; otherwise, check key permissions or network settings. Additionally, ensure the remote repository URL uses the SSH format (e.g., git@github.com:username/repo.git), not HTTPS.

Summary and Best Practices

The key to resolving "Permission denied (publickey)" errors lies in proper SSH authentication configuration. It is advisable to always use the Ed25519 algorithm for key generation, regularly update keys for security, and back up SSH config files. For multi-key environments, organizing config files can prevent conflicts. By following these steps, developers can ensure smooth Git operations and enhance productivity.