Lorixen.
EN

Git says 'Permission denied (publickey)'? Work through it

Short answer: "Permission denied (publickey)" means the Git host didn't accept any SSH key your computer or server offered. Usually the key isn't loaded, the wrong key is being offered, the key was never added to your account or repository, or the connection is being made as the wrong user, for example with sudo. Test the connection directly with ssh -T git@github.com (or your host's equivalent), add -v to see which keys are tried, and fix what the output shows. On servers, use a dedicated deploy key for each repository and pin it in your SSH config.

Step 1: test SSH on its own

Take Git out of the picture. GitHub's troubleshooting guide suggests:

ssh -T git@github.com

If it works, you'll see a greeting with your username. If you get Permission denied (publickey), the problem is SSH authentication, not your repository or branch.

GitLab and Bitbucket have equivalent test commands with their own hostnames.

Step 2: check you're connecting as "git"

GitHub's guide stresses that all SSH connections, including remote URLs, must use the git user. A remote URL with your own username, like alex@github.com:company/app.git, fails with exactly this error. Check with git remote -v, and fix the URL if needed with git remote set-url origin git@github.com:company/app.git.

Step 3: don't mix in sudo

GitHub's guide warns against using sudo with Git. If you generated your key as your normal user and then run sudo git pull, SSH runs as root, looks in root's key folder, finds nothing, and fails. This is common on servers where the site folder is owned by root or the web user. Fix ownership or run Git as the user that owns both the key and the folder.

Step 4: see which keys are offered

Run the test verbosely:

ssh -vT git@github.com

GitHub's guide shows how to read the output: which config files were read, which server you connected to, and which key files were tried. Look for lines mentioning "Offering public key" or "Trying private key". If your intended key never appears, SSH can't find it or isn't configured to use it.

Step 5: is the key loaded in the agent?

GitHub's guide shows starting the agent and listing loaded keys:

eval "$(ssh-agent -s)"
ssh-add -l

If your key isn't listed, add it with ssh-add ~/.ssh/your_key. After a restart, the agent may be empty again; many systems can load keys automatically at login.

Step 6: is the public key on the right account?

Compare the fingerprint of your key (ssh-add -l shows it) with the keys listed in your Git host account settings, or in the repository's deploy keys. A key added to a colleague's account, an old laptop's key, or a key added to the wrong repository won't work.

Step 7: too many keys, or the wrong one first

If you have several keys, SSH may offer them in an order that hits the wrong one first, or the server may reject the connection after too many attempts. The OpenSSH configuration manual describes IdentityFile to name the key for a host, and IdentitiesOnly, which tells SSH to use only the configured key even if the agent offers others. In ~/.ssh/config:

Host github.com
  IdentityFile ~/.ssh/id_ed25519_work
  IdentitiesOnly yes

Two accounts on one machine

If you use separate personal and work accounts, give each a host alias, such as github-work, with its own IdentityFile, and use git@github-work:company/app.git as the remote URL.

Servers and CI: use deploy keys

For a server that pulls code, don't copy your personal key onto it. Create a key pair on the server, add the public key as a read-only deploy key on that one repository, and pin it in the server user's SSH config as above. If the server needs several repositories, use one deploy key per repository with host aliases, since a deploy key generally can only be attached to one repository.

In CI, load the private key from the CI system's secrets into an agent for the job, and add the Git host's published host key to known_hosts rather than disabling host key checking.

Remove keys you no longer trust

When someone leaves or a laptop is lost, remove their key from your Git host and from any servers' authorised keys the same day. Review the list of keys and deploy keys on your account and repositories every few months; old, unexplained entries are exactly the access you don't want lingering.

File permissions

SSH refuses keys that other users can read. Your private key should be readable only by you, and your .ssh folder shouldn't be writable by others. If permissions are wrong, the verbose output usually says so.

Or switch to HTTPS

If SSH is blocked on a network, or you only need occasional access, an HTTPS remote with a credential helper or a personal access token is a valid alternative. Use whichever your team can manage consistently.

A worked example

An illustrative Brisbane café group's ordering site was deployed by running sudo git pull on the server. After the developer who set it up left, pulls failed with "Permission denied (publickey)". The verbose test showed root's key folder had no key; the old setup had depended on the developer's forwarded personal key. The new developer created a key for the deploy user, added it as a read-only deploy key on the repository, fixed folder ownership so sudo wasn't needed, and pinned the key in that user's SSH config.

FAQ

Do I need a new key for each computer?

It's good practice: lose a laptop, remove just that key.

Is RSA still okay?

Modern hosts recommend Ed25519 keys; older RSA keys may need to meet minimum sizes.

Why does it work in one terminal but not another?

Different users, shells or agents. Check ssh-add -l in each.

Can I use the same deploy key on two repositories?

Usually not; create one per repository.

If your team keeps hitting SSH and deploy access problems, describe how you deploy and we'll help you set up clean, per-server keys.

Sources

WhatsAppBook a call