Git uses Secure Shell (SSH) keys to authenticate users and authorize access to repositories. When you encounter a "Permission denied (publickey)" error, it usually indicates that your SSH key is not properly configured or not recognized by the Git server. In this tutorial, we will guide you through the process of setting up and troubleshooting SSH keys for Git authentication.
Generating SSH Keys
To start using SSH keys with Git, you need to generate a public/private key pair on your local machine. You can use the ssh-keygen command to create a new key pair. By default, the generated keys will be stored in the ~/.ssh directory.
cd ~/.ssh && ssh-keygen
You will be prompted to enter a filename for the key and a passphrase. If you don’t specify a filename, the default name will be used (e.g., id_rsa). It’s recommended to use a strong passphrase to protect your private key.
Copying the Public Key
Once you have generated the key pair, you need to copy the public key (id_rsa.pub) to the clipboard. The command to do this varies depending on your operating system:
- On OS X:
cat id_rsa.pub | pbcopy - On Linux:
cat id_rsa.pub | xclip - On Windows (via Cygwin/Git Bash):
cat id_rsa.pub | clip - On Windows (Powershell):
Get-Content id_rsa.pub | Set-Clipboard
Adding the Public Key to Your Git Account
To use your SSH key with Git, you need to add the public key to your account on the Git server. The process for doing this varies depending on the Git provider you are using:
- On GitHub: Go to your account settings > SSH and GPG keys > New SSH key
- On GitLab: Go to your account settings > SSH keys > Add SSH key
Paste the copied public key into the designated field and give it a label.
Configuring Your Git Client
To use your SSH key with Git, you need to configure your Git client to use the private key. You can do this by running the following commands:
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa
The first command starts the SSH agent in the background, and the second command adds your private key to the agent.
Troubleshooting
If you encounter issues with SSH key authentication, there are a few things you can try:
- Verify that your public key is correctly added to your Git account.
- Check that your private key is correctly configured on your local machine.
- Use the
ssh -vTcommand to test your SSH connection:ssh -vT [email protected] - If you are using Windows, ensure that Git is using the correct OpenSSH executable by running:
git config --global core.sshCommand "'C:\Windows\System32\OpenSSH\ssh.exe'"
Using HTTPS Instead of SSH
If you only need read-only access to a repository, you can use the HTTPS protocol instead of SSH. This avoids the need for public key authentication altogether. To clone a repository using HTTPS, simply replace the SSH URL with the HTTPS URL: https://github.com/username/repository.git
By following these steps and troubleshooting tips, you should be able to successfully configure SSH keys for Git authentication and avoid permission denied errors.