Introduction

Permission denied (publickey) means the Git host rejected the SSH authentication attempt. In practice, that usually comes down to one of four issues: the remote URL is using SSH when you expected HTTPS, the correct key does not exist locally, the SSH agent is not offering the right key, or the public key was never added to the Git hosting account.

Check the remote URL first

Start by confirming how the repository is configured:

git remote -v

If the URL looks like this:

[email protected]:owner/repo.git

then Git is using SSH. If you intended to use HTTPS instead, switch the remote:

git remote set-url origin https://github.com/owner/repo.git

If you do want SSH, keep going and verify the key setup.

Confirm that an SSH key exists

List the files in your SSH directory:

ls -la ~/.ssh

Typical key pairs include:

• 'id_ed25519 and id_ed25519.pub'
• 'id_rsa and id_rsa.pub'

If no suitable key exists, generate one:

ssh-keygen -t ed25519 -C "[email protected]"

That creates a private key and a matching public key. The private key stays on your machine. The public key is the part you upload to GitHub, GitLab, Bitbucket, or another Git host.

Load the key into the SSH agent

Even when the key exists, your current shell may not be using it. Add the private key to the agent:

ssh-add ~/.ssh/id_ed25519

Then check which identities are loaded:

ssh-add -l

If the expected key is missing from the agent, Git over SSH will usually fail. On systems with multiple terminal environments, it is worth testing in the same shell where Git itself is failing.

Add the public key to the Git host

Copy the public key and register it with your Git provider:

cat ~/.ssh/id_ed25519.pub

Make sure you copy the .pub file contents, not the private key. The server must know your public key before it will accept the matching private key during authentication.

Test SSH directly

Before debugging git pull or git push, test SSH itself:

ssh -T [email protected]

For GitLab:

ssh -T [email protected]

If that fails with the same error, the issue is with SSH configuration rather than Git commands specifically. For more detail, use verbose mode:

ssh -vT [email protected]

The verbose output shows which keys were offered and which host configuration was used.

Use SSH config when multiple keys exist

If you have several keys, tell SSH exactly which one to use:

1Host github.com
2  HostName github.com
3  User git
4  IdentityFile ~/.ssh/id_ed25519
5  IdentitiesOnly yes

This is often the cleanest fix when the client is offering too many keys or choosing the wrong one first. It is especially helpful when you use different keys for work and personal accounts.

Common Pitfalls

• Debugging Git commands before checking whether the remote is actually using SSH.
• Uploading the private key instead of the public key to the Git hosting account.
• Generating a key but forgetting to load it into the SSH agent.
• Having multiple SSH keys and assuming the client will choose the correct one automatically.

Summary

• 'Permission denied (publickey) is usually an SSH configuration problem, not a Git problem.'
• Confirm the remote URL, make sure a valid key pair exists, and load the correct key into the agent.
• Add the public key to your Git host and test with ssh -T.
• Use ~/.ssh/config when multiple keys or hosts are involved.