Fixing Git ‘Permission Denied (publickey)’ with SSH Agent on Ubuntu 22.04 LTS

Resolve Git 'Permission Denied (publickey)' errors on Ubuntu 22.04 LTS by troubleshooting SSH key agent issues, ensuring correct key setup, and proper Git host authentication.

When working with Git repositories over SSH, encountering a "Permission Denied (publickey)" error can halt your development or deployment workflows. This issue often signals a problem with how your SSH client (on Ubuntu 22.04 LTS) is presenting its authentication credentials (your SSH private key) to the remote Git server (e.g., GitHub, GitLab, Bitbucket). The error message "SSH key agent missing" further points to the ssh-agent utility, which is responsible for securely managing your private keys in memory.

Symptom & Error Signature

You will typically encounter this error when attempting to perform Git operations that require authentication with a remote server via SSH, such as git clone, git push, or git pull.

The output in your terminal might look similar to one of these:

[email protected]: Permission denied (publickey).

Please make sure you have the correct access rights and the repository exists. `

Or, with a more explicit "agent missing" hint (though this part is often inferred rather than explicitly stated by Git itself, ssh might report it with verbose output):

Cloning into 'my-repository'...
[email protected]: Permission denied (publickey).
The authenticity of host 'gitlab.com (X.X.X.X)' can't be established.
ED25519 key fingerprint is SHA256:....
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added 'gitlab.com' (ED25519) to the list of known hosts.
[email protected]: Permission denied (publickey).

Please make sure you have the correct access rights and the repository exists. `

In some verbose scenarios, you might see Agent admitted failure to sign using the key. or no mutual signature algorithm if the agent is running but lacks the correct key.

Root Cause Analysis

The "Permission Denied (publickey)" error, especially when combined with issues related to the ssh-agent, stems from one or more of the following underlying problems:

1. Missing or Unloaded Private Key: Your SSH private key (idrsa, ided25519, etc.) is either not present on your system, or it exists but has not been added to your ssh-agent for use. The ssh-agent acts as a key manager, allowing ssh and git to use your keys without repeatedly asking for passphrases.
2. ssh-agent Not Running or Misconfigured: The ssh-agent process, which holds your keys in memory, might not be running in your current shell session, or it may not have been correctly configured to start automatically with your desktop environment or terminal session.
3. Incorrect Private Key Permissions: SSH keys require strict file permissions (typically 600 for the private key and 700 for the .ssh directory). If permissions are too liberal, ssh will refuse to use the key for security reasons.
4. Public Key Not Registered with Git Hosting Service: Even if your private key is correctly set up locally, the corresponding public key (idrsa.pub, ided25519.pub) must be uploaded and registered with your Git hosting provider (GitHub, GitLab, Bitbucket) for your user account. The remote server uses this public key to verify your identity.
5. Incorrect Git Remote URL: You might be attempting to use an HTTPS remote URL (e.g., https://github.com/user/repo.git) instead of an SSH URL (e.g., [email protected]:user/repo.git). SSH authentication only works with SSH-formatted remote URLs.
6. ~/.ssh/config Issues: If you have a custom SSH configuration file (~/.ssh/config), it might be misconfigured, pointing to the wrong key, or overriding necessary default behaviors.
7. Key Passphrase Not Provided: If your private key is encrypted with a passphrase, and the ssh-agent is not running or the passphrase wasn't provided when adding the key to the agent, authentication will fail.

Step-by-Step Resolution

Follow these steps sequentially to diagnose and resolve the "Permission Denied (publickey)" error.

1. Verify SSH Key Existence and Permissions

First, ensure you have an SSH key pair and that its permissions are correctly set.

1. Check for existing keys:
2. `bash
3. ls -al ~/.ssh/
4. `
5. Look for files like idrsa, idrsa.pub, ided25519, ided25519.pub. If you see only .pub files or no id_* files, you might not have a key.

1. If no key exists, generate a new one:
2. `bash
3. ssh-keygen -t ed25519 -C "[email protected]"
4. `
5. > [!NOTE]
6. > ed25519 is the recommended modern key type. You can use rsa with -b 4096 for older compatibility if needed.
7. When prompted for a file to save the key, press Enter to accept the default (~/.ssh/id_ed25519).
8. Always set a strong passphrase for your private key. This encrypts your private key at rest, adding a crucial layer of security.

1. Set correct permissions for your .ssh directory and keys:
2. `bash
3. chmod 700 ~/.ssh
4. chmod 600 ~/.ssh/ided25519 # Or idrsa if you use RSA
5. chmod 644 ~/.ssh/ided25519.pub # Or idrsa.pub
6. `
7. > [!IMPORTANT]
8. > Incorrect permissions are a very common cause of SSH authentication failures. The private key must only be readable by the owner.

2. Start ssh-agent and Add Your Private Key

The ssh-agent process is key to managing your SSH identities.

1. Check if ssh-agent is running:
2. `bash
3. eval "$(ssh-agent -s)"
4. `
5. If it's already running, it will output something like SSHAUTHSOCK=/tmp/ssh-XXXXXX/agent.YYYY; export SSHAUTHSOCK; SSHAGENTPID=ZZZZZ; export SSHAGENTPID; echo Agent pid ZZZZZ;. If it wasn't running, this command will start it and set the necessary environment variables.

1. Add your private key to ssh-agent:
2. `bash
3. ssh-add ~/.ssh/id_ed25519 # Use the path to your private key
4. `
5. If your key has a passphrase, you will be prompted to enter it.
6. If you have multiple keys, add them all.
7. You can check which keys are loaded with ssh-add -l.

[!NOTE] > On Ubuntu, ssh-agent is often started automatically with your desktop environment. However, it might not be running in a specific terminal session, or it might not have your key loaded. The eval "$(ssh-agent -s)" and ssh-add commands are typically needed once per session or set up for persistence.

3. Verify Public Key on Git Hosting Service

Your remote Git server needs to know your public key to authenticate you.

1. Copy your public key to clipboard:
2. `bash
3. cat ~/.ssh/id_ed25519.pub
4. `
5. Copy the entire output, starting with ssh-ed25519 (or ssh-rsa) and ending with your email address.

1. Add the public key to your Git hosting provider:
2. * GitHub: Go to Settings -> SSH and GPG keys -> New SSH key. Paste your public key.
3. * GitLab: Go to User Settings -> SSH Keys. Paste your public key.
4. * Bitbucket: Go to Profile settings -> SSH keys. Add key.
5. * Self-hosted Git (e.g., Gitea, plain Git): You'll typically add it to the ~/.ssh/authorized_keys file of the git user on the server.

4. Validate Git Remote URL

Ensure your local Git repository is configured to use the SSH remote URL, not HTTPS.

1. Check current remote URLs:
2. Navigate to your repository directory and run:
3. `bash
4. git remote -v
5. `
6. Look for URLs starting with git@ (SSH) rather than https://.

Example of an SSH URL: ` origin [email protected]:yourusername/yourrepository.git (fetch) origin [email protected]:yourusername/yourrepository.git (push) `

Example of an HTTPS URL (which will cause issues): ` origin https://github.com/yourusername/yourrepository.git (fetch) origin https://github.com/yourusername/yourrepository.git (push) `

1. Change remote URL to SSH if necessary:
2. If you're using an HTTPS URL, update it to SSH:
3. `bash
4. git remote set-url origin [email protected]:yourusername/yourrepository.git
5. `
6. Replace yourusername/yourrepository.git with your actual repository path.

5. Test SSH Connection

Test your SSH connection to the Git hosting service. This verifies that your local SSH setup can authenticate.

ssh -T [email protected]
# Or for GitLab: ssh -T [email protected]
# Or for Bitbucket: ssh -T [email protected]
```

[!TIP] Use the -v flag for verbose output (ssh -vT [email protected]) if you're still facing issues. This can provide valuable debugging information about which keys are being tried and why they're failing.

6. Troubleshoot ~/.ssh/config (Advanced)

If you have a ~/.ssh/config file, it might be interfering.

1. Inspect ~/.ssh/config:
2. `bash
3. cat ~/.ssh/config
4. `
5. Look for Host entries related to your Git provider (e.g., Host github.com). Ensure any IdentityFile directives point to the correct private key and that there are no conflicting options.

A minimal working configuration might look like this: ` Host github.com Hostname ssh.github.com Port 443 User git IdentityFile ~/.ssh/id_ed25519 AddKeysToAgent yes UseKeychain yes # macOS specific, ignore on Ubuntu ` The Port 443 and Hostname ssh.github.com lines are useful if you're behind a firewall that blocks standard SSH port 22.

1. Temporarily disable ~/.ssh/config:
2. Rename it (mv ~/.ssh/config ~/.ssh/config_backup) and try connecting again. If it works, the issue is in your config file.

7. Persist ssh-agent Across Sessions (Optional but Recommended)

To avoid re-running eval "$(ssh-agent -s)" and ssh-add every time you open a new terminal or reboot, configure your shell to handle this automatically.

1. For Bash users:
2. Edit your ~/.bashrc file:
3. `bash
4. nano ~/.bashrc
5. `
6. Add the following lines at the end:
7. `bash
8. # Start ssh-agent if not running
9. if [ -z "$SSHAUTHSOCK" ]; then
10. eval "$(ssh-agent -s)"
11. ssh-add ~/.ssh/id_ed25519 # Add your private key here
12. fi
13. `
14. Save the file and exit (Ctrl+X, Y, Enter).
15. Then, apply the changes: source ~/.bashrc.

1. For Zsh users:
2. Edit your ~/.zshrc file:
3. `bash
4. nano ~/.zshrc
5. `
6. Add the same lines as for Bash. Save, exit, and then source ~/.zshrc.

[!WARNING] > While convenient, ssh-add in .bashrc/.zshrc will prompt for your passphrase every time a new shell is opened if the agent doesn't already have the key. A more robust solution might involve using keychain (if available on Ubuntu) or relying on desktop environment integration. For most server environments where you login via SSH directly, the above if block is a practical solution.

By systematically following these steps, you should be able to resolve the "Permission Denied (publickey)" error caused by SSH key agent issues on your Ubuntu 22.04 LTS system and resume your Git operations.