[Fixed] Permission denied (publickey) in Git SSH: Step-by-Step Troubleshooting Guide

Executive Summary & Root Cause Analysis: The error git@github.com: Permission denied (publickey). fatal: Could not read from remote repository (also seen on GitLab and Bitbucket) occurs when the remote Git host rejects your SSH authentication handshake. Unlike HTTPS, SSH authentication relies on asymmetric cryptographic key pairs rather than passwords or Personal Access Tokens. Common root causes include: (1) the SSH agent (ssh-agent) is not running or does not have your private key loaded in memory, (2) the corresponding public key (.pub) has not been uploaded to your Git hosting account, (3) overly permissive file permissions on ~/.ssh causing OpenSSH to ignore your keys, and (4) using a non-default key filename without specifying it in ~/.ssh/config.

Step 1: Quick Fix – Start ssh-agent and Load Your Private Key

In many terminal sessions (especially after a reboot, inside WSL2, or on Git Bash for Windows), your SSH key exists on disk but is not loaded into the active ssh-agent.

# 1. List existing SSH keys in your ~/.ssh directory
ls -al ~/.ssh

# 2. Start the ssh-agent in the background
eval "$(ssh-agent -s)"

# 3. Check if any keys are currently loaded
ssh-add -l

# 4. Add your private key (commonly id_ed25519 or id_rsa)
ssh-add ~/.ssh/id_ed25519

# On macOS, persist the passphrase in Keychain:
# ssh-add --apple-use-keychain ~/.ssh/id_ed25519

If you do not have an SSH key pair yet, generate a modern Ed25519 key and add it to the agent:

ssh-keygen -t ed25519 -C "your_email@example.com"
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

Step 2: Verify File Permissions and SSH Config

OpenSSH strictly refuses to read private keys if other system users have read or write access to your ~/.ssh directory or key files. Additionally, if you use multiple Git accounts or custom key names, you must map them explicitly.

# Fix restrictive permissions required by OpenSSH (Linux / macOS / WSL)
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub

Next, ensure your ~/.ssh/config file points to the correct identity file (especially important when managing personal and work GitHub accounts):

# Add or update ~/.ssh/config
Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes

Finally, copy your public key (cat ~/.ssh/id_ed25519.pub) and confirm it is registered under Settings > SSH and GPG keys on GitHub, GitLab, or Bitbucket.

Step 3: Alternative Workarounds – Verbose Debugging & HTTPS Fallback

If the error persists, inspect the exact SSH handshake in verbose mode or switch your remote URL to HTTPS if your corporate firewall blocks port 22:

  1. Run SSH in verbose mode to see which key is offered:
    # Prints detailed connection and identity file negotiation logs
    ssh -vT git@github.com
  2. Check your repository remote URL format:
    # Ensure the remote uses 'git@' (never your personal username@)
    git remote -v
    
    # Correct malformed SSH URL if needed:
    git remote set-url origin git@github.com:username/repository.git
  3. Switch to HTTPS remote temporarily (if SSH port 22 is blocked):
    git remote set-url origin https://github.com/username/repository.git

Verification & Testing Steps

Confirm that your SSH handshake authenticates cleanly and that Git remote operations succeed:

# Test SSH authentication directly against GitHub (or gitlab.com)
ssh -T git@github.com
# Expected output: "Hi <username>! You've successfully authenticated, but GitHub does not provide shell access."

# Test remote fetch/pull inside your repository
git fetch origin
git status

Summary Comparison Table

Root Cause Diagnostic Clue Recommended Fix Scope
Key not loaded in agent ssh-add -l returns The agent has no identities eval "$(ssh-agent -s)" && ssh-add ~/.ssh/id_ed25519 Current session / Keychain
Insecure ~/.ssh permissions ssh -vT skips key with permission warning chmod 700 ~/.ssh && chmod 600 ~/.ssh/id_* Permanent on host
Custom key name / multi-account ssh -vT offers wrong default key Configure IdentityFile & IdentitiesOnly yes in ~/.ssh/config Permanent per host alias
Public key missing on Git host Key is offered in ssh -vT but rejected Upload ~/.ssh/*.pub to GitHub/GitLab settings Account-wide

Leave a Reply