Resolving ‘Git permission denied (publickey)’ due to Missing SSH Agent on Ubuntu 20.04 LTS

Troubleshoot and fix 'permission denied (publickey)' Git errors on Ubuntu 20.04 LTS. This guide addresses missing SSH key agent issues for seamless Git repository access.

Introduction

As a seasoned Systems Administrator or DevOps engineer, encountering a Permission denied (publickey) error when attempting Git operations over SSH is a common, yet frustrating, experience. This particular guide focuses on the specific scenario where the underlying issue on your Ubuntu 20.04 LTS client machine is related to the SSH key agent (ssh-agent) not running, or not having your necessary private key loaded. This prevents your Git client from presenting a valid cryptographic identity to remote Git servers like GitHub, GitLab, or Bitbucket, leading to authentication failure.

This guide will systematically walk you through diagnosing and resolving this issue, ensuring your SSH keys are correctly managed and recognized by your system for seamless Git workflow.

Symptom & Error Signature

Users typically encounter this error when executing git clone, git pull, git push, or even a simple ssh -T [email protected] (or other Git service domain). The output will clearly indicate an authentication failure related to publickey validation.

$ git clone [email protected]:youruser/your-repository.git
Cloning into 'your-repository'...
[email protected]: Permission denied (publickey).
fatal: Could not read from remote repository.

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

Another diagnostic command often run, which yields a similar signature:

$ ssh -T [email protected]
[email protected]: Permission denied (publickey).

Root Cause Analysis

The "permission denied (publickey)" error specifically points to an issue where the SSH client cannot successfully authenticate using a private key. When the "SSH key agent missing" aspect is factored in, the root causes usually boil down to one or more of the following:

1. ssh-agent Not Running: The ssh-agent is a background program that stores decrypted private keys in memory. Git operations using SSH rely on this agent to provide the private key counterpart to the public key presented to the remote server. If the agent isn't running, or if the shell environment isn't correctly configured to communicate with it, authentication fails.
2. Private Key Not Loaded into ssh-agent: Even if ssh-agent is active, the specific private key required for authenticating with the Git remote might not have been added to it using ssh-add. The agent cannot use a key it doesn't possess.
3. Incorrect Key Permissions: SSH enforces strict permissions on private key files (~/.ssh/id_rsa, ~/.ssh/id_ed25519, etc.). If these permissions are too liberal (e.g., world-readable), SSH will refuse to use the key for security reasons, often resulting in a Permission denied error.
4. No SSH Key Generated: The most fundamental issue – a private/public key pair simply doesn't exist in the ~/.ssh directory. While the error hints at a public key attempt, it implies a key should be available.
5. Public Key Not Registered on Git Host: The corresponding public key (.pub file) must be registered with your user account on the Git hosting service (GitHub, GitLab, Bitbucket). Without this, the server has no way to verify your identity.
6. Incorrect ~/.ssh/config (Less Common for this specific symptom): While less direct to the "agent missing" aspect, a misconfigured ~/.ssh/config file could direct SSH to look for keys in non-standard locations or ignore the agent, though this usually manifests with different diagnostic output.

For the scope of this guide, we will primarily focus on resolving issues related to the ssh-agent and key management on the client side.

Step-by-Step Resolution

Follow these steps to diagnose and resolve the "permission denied publickey SSH key agent missing" error on your Ubuntu 20.04 LTS system.

1. Verify SSH Agent Status and Loaded Keys

First, let's confirm if an ssh-agent is running and if any keys are currently loaded.

# Check if SSH_AUTH_SOCK is set, indicating an agent is potentially running
echo "$SSH_AUTH_SOCK"

# List keys currently loaded into the agent
ssh-add -l

Expected Output Analysis:

• If echo "$SSH_AUTH_SOCK" is empty, or ssh-add -l returns Could not open a connection to your authentication agent., the ssh-agent is likely not running or your current shell isn't configured to communicate with it.
• If ssh-add -l returns The agent has no identities., the agent is running, but no private keys are loaded.
• If it lists keys, proceed to Step 5 (Verify Connectivity) to ensure the correct key is loaded and functional.

2. Start the SSH Agent (if not running)

If the agent is not running or not accessible, you need to start it and set the necessary environment variables.

eval "$(ssh-agent -s)"

This command starts the ssh-agent in the background and sets the SSH_AUTH_SOCK and SSH_AGENT_PID environment variables in your current shell. These variables tell other SSH-related programs (like Git's SSH client) how to communicate with the agent.

The eval "$(ssh-agent -s)" command only configures the agent for your current shell session. To make it persistent across new terminal windows or reboots, you'll need to configure your shell's startup files (see Step 4).

3. Ensure SSH Keys are Generated and Have Correct Permissions

If you haven't generated an SSH key pair before, or are unsure, generate one. Ed25519 is recommended for security and performance.

# Check for existing keys
ls -la ~/.ssh/id_rsa* ~/.ssh/id_ed25519* 2>/dev/null

# If no keys exist, generate a new Ed25519 key pair
# Replace "[email protected]" with your actual email
ssh-keygen -t ed25519 -C "[email protected]"

When prompted for a file to save the key, press Enter to accept the default (~/.ssh/id_ed25519). You'll also be prompted for a passphrase. While optional, using a strong passphrase is a critical security practice for private keys.

Next, ensure your .ssh directory and key files have the correct, strict permissions. Incorrect permissions are a common cause of SSH key failures.

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519    # Or ~/.ssh/id_rsa if you use RSA
chmod 644 ~/.ssh/id_ed25519.pub # Or ~/.ssh/id_rsa.pub

Your private key file (id_ed25519 or id_rsa) must have permissions set to 600 (read/write only for the owner). SSH will outright ignore private keys with more permissive settings for security reasons. The ~/.ssh directory should be 700.

4. Add Your Private Key to the SSH Agent

With the agent running and keys generated, add your private key to the ssh-agent.

ssh-add ~/.ssh/id_ed25519 # Use the path to your private key (e.g., ~/.ssh/id_rsa)

If your key has a passphrase, you will be prompted to enter it. Once entered, the key will be decrypted and stored in the agent's memory for the duration of its lifespan or until explicitly removed.

Verify again that your key is now loaded:

ssh-add -l

You should now see an entry similar to: 256 SHA256:abcd... [email protected] (ED25519)

5. Configure Your Shell for Automatic SSH Agent Management

To avoid manually starting the agent and adding keys every time you open a new terminal or log in, configure your shell's startup script (e.g., ~/.bashrc for Bash or ~/.zshrc for Zsh).

Add the following block to the end of your ~/.bashrc file:

echo '
# Start ssh-agent if not already running, and load keys
if [ -z "$SSH_AUTH_SOCK" ]; then
  eval "$(ssh-agent -s)"
  # Add your primary SSH key(s) here. Replace id_ed25519 with your key filename.
  # For keys with passphrases, you might still be prompted on first use per session.
  ssh-add ~/.ssh/id_ed25519 2>/dev/null
  # ssh-add ~/.ssh/id_rsa 2>/dev/null # Uncomment if you also use an RSA key
fi
' >> ~/.bashrc

Apply the changes to your current session:

source ~/.bashrc

Now, when you open a new terminal, the script will check if SSH_AUTH_SOCK is set. If not, it will start ssh-agent and attempt to load your specified keys. The 2>/dev/null suppresses output if the key is already loaded or not found.

For servers or CI/CD environments where user interaction is undesirable, consider using SSH keys without passphrases, but ensure their security by restricting their usage in the remote authorized_keys file (e.g., command="...",no-port-forwarding,...). For interactive development environments, a passphrase is highly recommended.

6. Ensure Your Public Key is Registered with the Git Service

Even with a perfectly configured client, authentication will fail if the Git hosting service doesn't have your corresponding public key.

Retrieve your public key:

cat ~/.ssh/id_ed25519.pub

Copy the entire output, which starts with ssh-ed25519 (or ssh-rsa) and ends with your email comment.

Then, navigate to your Git hosting provider's website and add this public key:

• GitHub: Go to Settings -> SSH and GPG keys -> New SSH key.
• GitLab: Go to User Settings -> SSH Keys.
• Bitbucket: Go to Settings -> SSH keys.

Paste your public key into the provided text area and save it.

7. Verify Connectivity to Git Host

Finally, re-test your SSH connection to the Git service.

ssh -T [email protected] # For GitHub
# ssh -T [email protected] # For GitLab
# ssh -T [email protected] # For Bitbucket

Expected Successful Output:

Hi yourusername! You've successfully authenticated, but GitHub does not provide shell access.

(The exact message may vary slightly depending on the Git service).

If you receive this message, your SSH agent is correctly configured, your key is loaded, and the Git service recognizes your public key. You should now be able to perform Git operations over SSH without the permission denied (publickey) error.