Resolving 'Permission Denied (publickey)' Error When Cloning GitHub Repository

Comprehensive guide to troubleshooting SSH authentication issues in Git

Key Takeaways

Ensure your SSH keys are properly configured and added to your GitHub account.
Verify that you have the correct permissions and repository access.
Properly set up and manage your SSH agent to handle your keys.

Understanding the 'Permission Denied (publickey)' Error

The Permission denied (publickey) error occurs when GitHub cannot authenticate your connection using SSH keys. This prevents you from cloning, pulling, or pushing to repositories using SSH. The root causes typically involve misconfigured SSH keys, incorrect permissions, or issues with the SSH agent.

Step-by-Step Troubleshooting Guide

1. Verify SSH Key Existence

First, check if you already have an SSH key pair on your local machine.

ls -al ~/.ssh

Look for files named id_rsa and id_rsa.pub or id_ed25519 and id_ed25519.pub. If these files exist, you have an SSH key pair set up.

2. Generate a New SSH Key (If Needed)

If you do not have an SSH key pair, generate one using the following command:

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

If your system does not support ed25519, use rsa with a 4096-bit key:

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

Follow the prompts to save the key in the default location (~/.ssh/id_ed25519 or ~/.ssh/id_rsa).

3. Add the SSH Key to the SSH Agent

Start the SSH agent and add your private key:


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

If you used a different key filename, replace id_ed25519 with your key's name.

4. Add the Public Key to Your GitHub Account

Copy your public key to the clipboard:

cat ~/.ssh/id_ed25519.pub

Follow these steps to add the key to GitHub:

Log in to your GitHub account.
Navigate to Settings > SSH and GPG keys.
Click on New SSH key.
Provide a title for the key (e.g., "My Laptop SSH Key").
Paste the copied public key into the key field.
Click Add SSH key.

5. Test the SSH Connection

Verify that your SSH key is correctly configured by testing the connection to GitHub:

ssh -T git@github.com

You should receive a message like:


Hi username! You've successfully authenticated, but GitHub does not provide shell access.

6. Check Repository Permissions

Ensure that the repository keli/ctp-python exists and that your GitHub account has the necessary permissions to access it. If the repository is private, you must be added as a collaborator or have the appropriate access rights.

7. Verify the Correct SSH URL

Double-check that you're using the correct SSH URL for cloning:

git clone git@github.com:keli/ctp-python.git

Ensure there are no typos and that the repository path matches exactly.

8. Set Correct Permissions on SSH Key

Ensure that your private key file has the correct permissions to prevent unauthorized access:

chmod 600 ~/.ssh/id_ed25519

This command restricts the file permissions so that only the owner can read and write the file.

9. Ensure Matching Email

Make sure the email associated with your SSH key matches the email used in your GitHub profile:

git config --global user.email

If it doesn't match, update it:

git config --global user.email "your_email@example.com"

10. Firewall and Proxy Check

If you're behind a company firewall or proxy, SSH traffic on port 22 might be blocked. To resolve this:

Configure Git to use the HTTPS URL instead:

git remote set-url origin https://github.com/keli/ctp-python.git

Or use GitHub's SSH on port 443:

ssh -T -p 443 git@github.com

11. Final Test: Clone the Repository

After performing the above steps, attempt to clone the repository again:

git clone git@github.com:keli/ctp-python.git

If the issue persists, consider debugging the SSH connection:

ssh -vvv git@github.com

This verbose mode provides detailed information about the SSH connection process, helping identify where the authentication is failing.

Best Practices for Managing SSH Keys

To prevent future authentication issues, adhere to the following best practices:

Use Strong Encryption: Prefer ed25519 over rsa for better security and performance.
Protect Your Private Key: Ensure your private key file has restricted permissions (chmod 600).
Regularly Update Keys: Rotate your SSH keys periodically to enhance security.
Use SSH Configurations: Create a ~/.ssh/config file to manage multiple SSH keys and settings efficiently.

Troubleshooting Common Issues

Incorrect SSH Key Added to GitHub

Ensure that the correct public key is added to your GitHub account. If multiple keys exist, verify that the one you intend to use is the one linked to GitHub.

Multiple SSH Keys and Configuration Conflicts

If you have multiple SSH keys, specify which key to use for GitHub by configuring the SSH config file:


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

SSH Agent Not Running

Ensure that the SSH agent is running and has your key added. You can start the agent and add your key using:


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

Advanced Configuration

Using SSH Key Passphrases

For added security, you can protect your SSH keys with a passphrase. When generating the key, you will be prompted to enter one. This ensures that even if someone gains access to your private key, they cannot use it without the passphrase.

Integrating SSH with Git GUI Clients

If you use Git GUI clients like GitKraken or SourceTree, ensure they are configured to use your SSH keys correctly. Refer to the respective documentation for integration steps.

Recap and Conclusion

Encountering the Permission denied (publickey) error when attempting to clone a GitHub repository via SSH is a common issue that can be resolved by carefully following a series of troubleshooting steps. By verifying the existence and correctness of your SSH keys, ensuring they are properly added to your GitHub account, and confirming your repository permissions, you can effectively overcome this authentication hurdle. Additionally, adhering to SSH best practices and addressing common configuration issues will help maintain a smooth and secure workflow with Git and GitHub.