Fix Permission Denied (Publickey) Error on GitHub

You are ready to share your work. You type the push command, wait a second, and Git stops with a short but confusing message: “Permission denied (publickey).” Nothing was uploaded, and the error does not tell you what went wrong or where to look first.

This error is very common, especially for beginners using SSH with GitHub for the first time. The good news is that it almost never means your code is broken. It simply means GitHub could not confirm who you are using an SSH key, so it refused the connection to protect your account.

In this guide, you will learn what the error means, how to test your connection step by step, and how to fix the problem on Windows, macOS, and Linux. By the end, you should be able to push with confidence and know how to check things quickly if the error ever returns.

Quick Answer

The “Permission denied (publickey)” error means GitHub did not accept the SSH key your computer offered. To fix it, create an SSH key with ssh-keygen, add the private key to the SSH agent, copy the public key to your GitHub account under SSH settings, and then test the connection with ssh -T git@github.com before pushing again.

What Does Permission Denied (Publickey) Actually Mean?

When you connect to GitHub with SSH, your computer proves your identity with a pair of keys. One key is private and stays secret on your computer. The other key is public and is safe to share with GitHub.

During a connection, GitHub checks whether the public key it has on file matches a private key on your computer. If there is no match, GitHub cannot be sure you are the account owner. It closes the connection and shows the publickey error.

The Most Common Causes

• You have never created an SSH key on this computer.
• You created a key but never added the public key to GitHub.
• The SSH agent is not running, so your key is not being offered.
• You have several keys and Git is offering the wrong one.
• Your remote URL uses SSH, but you expected to log in with a password.
• The key file has the wrong permissions and SSH refuses to use it.

Most fixes take less than ten minutes. Work through the steps in order and test after each major step.

Step 1: Check Whether Your Remote Uses SSH

First, confirm that your project is actually using an SSH address. Open a terminal inside your project folder and run this command:

git remote -v

If the address starts with git@github.com:, you are using SSH. An https:// address uses HTTPS instead.

If you are new to setting up Git itself, our guide on how to install Git on Windows 11 correctly walks through the first-time setup in simple steps.

Step 2: Test Your SSH Connection to GitHub

Before changing anything, run GitHub’s own test command:

1. Open your terminal or Git Bash.
2. Type ssh -T git@github.com and press Enter.
3. If asked whether you want to continue connecting, type yes.
4. Read the reply carefully.

If it works, you will see a friendly message with your GitHub username, saying you have successfully authenticated. If it fails, you will see the same permission denied message, which confirms the problem is with your key, not with your project.

Step 3: Check for Existing SSH Keys

You may already have a key and simply need to add it to GitHub. Check the default SSH folder first.

1. On macOS and Linux, run ls -al ~/.ssh.
2. On Windows, check the folder C:\Users\YourName\.ssh in File Explorer, or run the same command in Git Bash.
3. Look for files named id_ed25519 and id_ed25519.pub, or older names like id_rsa and id_rsa.pub.

The file ending in .pub is your public key and is safe to share. The file without that ending is private — never share or upload it.

If those files do not exist, create a new key in the next step. If they do exist, skip ahead to adding the public key to GitHub.

Step 4: Create a New SSH Key

Creating a key takes one command. Use the email address linked to your GitHub account so you can recognise the key later.

1. Run ssh-keygen -t ed25519 -C "your_email@example.com".
2. When asked where to save the key, press Enter to accept the default location.
3. When asked for a passphrase, choose a strong one you will remember, or press Enter for none if this is a private personal computer.
4. Wait for the confirmation message showing the key was saved.

Ed25519 is the modern, secure choice recommended for most users and supported by GitHub.

Step 5: Add Your Key to the SSH Agent

The SSH agent is a small background helper that holds your private key ready for use. Without it, Git may not offer your key even though the files exist on your disk.

On macOS and Linux

1. Start the agent with eval "$(ssh-agent -s)".
2. Add your key with ssh-add ~/.ssh/id_ed25519.
3. Enter your passphrase if you set one.

On Windows

1. Open Git Bash and run eval $(ssh-agent -s).
2. Add your key with ssh-add ~/.ssh/id_ed25519.

Run ssh-add -l to check which keys the agent holds. If the list is empty, your key is not loaded yet.

Step 6: Add the Public Key to GitHub

This is the step beginners miss most often. Creating a key on your computer is only half the job. GitHub also needs the public half.

1. Copy your public key. On macOS use pbcopy < ~/.ssh/id_ed25519.pub. On Windows Git Bash use clip < ~/.ssh/id_ed25519.pub. On Linux, open the .pub file and copy the whole single line.
2. Open GitHub in your browser and sign in.
3. Click your profile picture, then open Settings.
4. Choose “SSH and GPG keys” from the side menu.
5. Click “New SSH key”, give it a clear title such as “My Laptop”, and paste the key.
6. Click “Add SSH key” and confirm if GitHub asks for your password.

The official GitHub guide to connecting with SSH shows this process with screenshots if you want to compare each screen as you go.

Copy the full line, starting with ssh-ed25519, without extra spaces or line breaks.

Step 7: Test Again and Push

Now repeat the test from Step 2:

ssh -T git@github.com

You should see a success message with your username. A note that GitHub does not provide shell access is normal.

Go back to your project folder and try your push again:

git push origin main

Use your real branch name if it is not called main. In most cases, the push will now complete without any password prompt.

Still Not Working? Advanced Checks

If the basic steps did not help, check three things. First, if you have multiple keys, add a block for GitHub in ~/.ssh/config with Host github.com, User git, and IdentityFile ~/.ssh/id_ed25519 so SSH offers the right key. Second, on macOS and Linux fix permissions with chmod 700 ~/.ssh and chmod 600 ~/.ssh/id_ed25519. Third, check the username in the test message — the key may belong to a different account without access to the repository.

The GitHub SSH troubleshooting documentation covers rarer cases, such as blocked ports, in helpful detail.

Common Mistakes to Avoid

• Sharing the private key: Only the .pub file goes to GitHub. The private key never leaves your computer.
• Adding the key to the wrong account: Many people are signed into a work account in the browser while pushing to a personal repo, or the other way around.
• Skipping the test command: Testing with ssh -T git@github.com saves time because it separates key problems from project problems.
• Typing the key by hand: Always copy and paste the public key. One missing character breaks the match completely.

Conclusion

The “Permission denied (publickey)” error looks scary, but its meaning is simple: GitHub could not match a key from your computer to a key saved on your account. Once you create a key, load it into the agent, and add the public part to GitHub, the connection usually works right away.

Work through the steps in order — check the remote, test the connection, find or create a key, add it to the agent and to GitHub, then test again. That calm order fixes the problem for most people and teaches you a skill you will reuse on every new computer you set up for development.

Frequently Asked Questions

Can I use the same SSH key on two computers?

No, it is better to create a separate key for each computer. That way, if you lose one device, you can remove only that key from GitHub and your other computers keep working without any change.

What is the difference between SSH and HTTPS for GitHub?

With HTTPS, you authenticate with a personal access token when you push. With SSH, you authenticate with your key pair and do not type a token each time. Both are secure, and many developers prefer SSH for daily work because it feels smoother after setup.

I forgot my key passphrase. What should I do?

A lost passphrase cannot be recovered. Create a new key pair, add the new public key to GitHub, and remove the old public key from your account settings. Your projects and history are not affected.

Why does the test succeed but my push still fails?

Your key may belong to an account without access to that specific repository. Check the username in the test message, confirm the remote address is correct with git remote -v, and ask the repo owner to confirm your access.

Do I need to remove old keys from GitHub?

Yes, it is good practice. Remove keys for computers you no longer own or use. This keeps your account safer and makes it obvious which key belongs to which device when you are troubleshooting.