Troubleshooting ‘Git permission denied (publickey)’ due to Missing SSH Agent on CentOS Stream / Rocky Linux

Resolve 'Git permission denied (publickey)' on CentOS Stream/Rocky Linux. This guide addresses missing SSH agent issues, ensuring smooth Git operations over SSH.

Introduction

As a seasoned Systems Administrator or DevOps engineer, encountering "Permission denied (publickey)" during Git operations over SSH is a common, yet often frustrating, experience. While this error can stem from various causes, a frequent culprit on CentOS Stream or Rocky Linux systems is a misconfigured or missing SSH agent. This guide will walk you through diagnosing and resolving issues related to your SSH key agent, ensuring your Git commands execute flawlessly.

The SSH agent (ssh-agent) is a background program that holds your private keys in memory, preventing you from having to type your passphrase every time you use an SSH key. When Git tries to connect to a remote repository via SSH and the agent isn't running, or your keys aren't loaded, or the environment variables pointing to the agent aren't set, you'll hit this "permission denied" roadblock.

Symptom & Error Signature

When attempting to perform Git operations like clone, pull, or push over SSH, you will typically see output similar to one of these variations:

git clone [email protected]:your-user/your-repo.git
Cloning into 'your-repo'...
[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.

or sometimes with more verbose SSH debugging:

GIT_SSH_COMMAND="ssh -vvv" git push origin main
...
debug1: Authentications that can continue: publickey
debug1: Next authentication method: publickey
debug1: Trying private key: /home/your-user/.ssh/id_rsa
debug1: Trying private key: /home/your-user/.ssh/id_dsa
debug1: Trying private key: /home/your-user/.ssh/id_ecdsa
debug1: Trying private key: /home/your-user/.ssh/id_ed25519
debug1: No more authentication methods to try.
[email protected]: Permission denied (publickey).
fatal: Could not read from remote repository.

The key indicators here are Permission denied (publickey) and the explicit mention of private keys being tried without success, often because the ssh-agent isn't supplying them.

Root Cause Analysis

The "Git error permission denied publickey SSH key agent missing" on CentOS Stream / Rocky Linux typically points to one or more of the following underlying issues:

1. ssh-agent Not Running: The SSH agent process itself might not be active, meaning there's no service to hold your private keys.
2. SSH_AUTH_SOCK Environment Variable Missing/Incorrect: Even if ssh-agent is running, your current shell session needs to know how to communicate with it. This is done via the SSH_AUTH_SOCK environment variable, which points to the agent's Unix domain socket. If this variable isn't set or is pointing to a stale/incorrect socket, ssh clients (including Git's underlying SSH client) won't find the agent.
3. SSH Key Not Added to Agent: The ssh-agent might be running, and your shell might be configured to use it, but you haven't explicitly added your private key(s) to the agent's memory using ssh-add.
4. Incorrect SSH Key Passphrase: If your private key is protected by a passphrase, ssh-add will prompt for it. An incorrect passphrase will prevent the key from being loaded into the agent.
5. Incorrect File Permissions: Strict permissions are required for SSH keys and the ~/.ssh directory. If these are too open, SSH will ignore the keys for security reasons.
6. Public Key Not Registered on Git Host: While less directly related to the agent being missing, if your corresponding public key (id_rsa.pub, id_ed25519.pub, etc.) is not uploaded to your Git service provider (GitHub, GitLab, Bitbucket) or is incorrect, the server will reject your authentication attempt, leading to a Permission denied (publickey) error. This is a crucial step to check if agent issues are resolved but the problem persists.
7. SSH Configuration Issues (~/.ssh/config): Less common for this specific error signature, but a misconfigured Host entry in ~/.ssh/config could lead to SSH not attempting the correct authentication method or using the wrong key.

Step-by-Step Resolution

Follow these steps to diagnose and resolve the SSH agent issue on your CentOS Stream or Rocky Linux system.

1. Verify ssh-agent Status and Loaded Keys

First, let's check if an ssh-agent is running in your current shell and if any keys are loaded.

# Check if SSH_AUTH_SOCK is set (indicating an agent connection)
echo "$SSH_AUTH_SOCK"

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

Expected Output (if agent is running and keys are loaded):

/tmp/ssh-XXXXXX/agent.YYYYY
4096 SHA256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx user@hostname (RSA)

If SSH_AUTH_SOCK is empty or ssh-add -l returns Could not open a connection to your authentication agent., then your ssh-agent is not running or your current shell isn't connected to it. This is the primary problem we need to fix.

2. Start the SSH Agent and Connect Your Shell

If the agent is not running or your shell is not connected, you need to start it and set the necessary environment variables. The eval "$(ssh-agent -s)" command is the standard way to do this.

eval "$(ssh-agent -s)"

Expected Output:

Agent pid 12345

This command starts ssh-agent and then executes the shell commands it prints (which set SSH_AUTH_SOCK and SSH_AGENT_PID). After running this, re-check echo "$SSH_AUTH_SOCK" and ssh-add -l. ssh-add -l should now return The agent has no identities..

Running eval "$(ssh-agent -s)" will start a new agent if one isn't already running in your session, or connect to an existing one if available. The environment variables set are crucial for your shell to communicate with the agent. This setup is per-shell session unless persisted.

3. Add Your SSH Key to the Agent

Now that the ssh-agent is running and your shell is connected, add your private SSH key(s) to it. The default private key path is ~/.ssh/id_rsa or ~/.ssh/id_ed25519.

ssh-add ~/.ssh/id_rsa
# If you use a different key type, e.g., Ed25519
# ssh-add ~/.ssh/id_ed25519

If your key is protected by a passphrase, you will be prompted to enter it.

Enter passphrase for /home/your-user/.ssh/id_rsa:
Identity added: /home/your-user/.ssh/id_rsa (user@hostname)

If you have multiple keys, add them all using ssh-add /path/to/your/key. You can list all loaded keys again with ssh-add -l.

4. Verify SSH Key Permissions

Incorrect file permissions are a common reason for SSH keys being ignored. Ensure your ~/.ssh directory and your private key file have the correct, strict permissions.

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_rsa # Or your specific private key file

Never set group or world-writable permissions on your private keys (chmod 604, 644, etc.) or the ~/.ssh directory (chmod 755, 777). SSH will silently ignore keys with insecure permissions, leading to Permission denied. Your public key (id_rsa.pub) can be more permissive (chmod 644).

5. Verify Public Key on Git Host

Even if your SSH agent is perfectly configured, the Git service (GitHub, GitLab, Bitbucket) needs to recognize your public key.

1. Get your public key:

   cat ~/.ssh/id_rsa.pub
   # Or for Ed25519
   # cat ~/.ssh/id_ed25519.pub
   

2. Copy the entire output.
3. Go to your Git service provider's settings:
   • GitHub: Settings -> SSH and GPG keys -> New SSH key
   • GitLab: User Settings -> SSH Keys
   • Bitbucket: Bitbucket settings -> SSH keys
4. Paste your public key into the designated field and save it.

Make sure you are using the correct public key that corresponds to the private key you added to your ssh-agent. Each public key starts with ssh-rsa or ssh-ed25519 and ends with a comment (usually user@hostname).

6. Test Your SSH Connection

After performing the above steps, test your SSH connection to the Git host. This will confirm that SSH can authenticate successfully.

# For GitHub
ssh -T [email protected]

# For GitLab (adjust if self-hosted)
ssh -T [email protected]

Expected Output (for GitHub, similar for others):

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

If you see this message, congratulations! Your SSH agent and key setup are working correctly. You can now proceed with your Git operations.

If you still receive Permission denied (publickey), re-verify each step, especially ssh-add -l and the public key on the Git host. Use ssh -vT [email protected] for verbose debugging output to pinpoint where the authentication is failing.

7. Persist the SSH Agent Across Sessions (Optional, but Recommended for User Sessions)

The eval "$(ssh-agent -s)" command only sets up the agent for your current shell session. If you close your terminal or open a new one, you'll have to repeat steps 2 and 3. To persist the agent and key loading, especially for interactive user sessions, you can add commands to your shell's startup file:

# Edit your shell's startup file (e.g., .bashrc for Bash, .zshrc for Zsh)
nano ~/.bashrc

Add the following block to the end of the file:

# Start SSH agent if not running, add keys
if [ -z "$SSH_AUTH_SOCK" ]; then
    eval "$(ssh-agent -s)"
    # Add your default keys automatically
    # Check if id_rsa exists and add it
    if [ -f "$HOME/.ssh/id_rsa" ]; then
        ssh-add "$HOME/.ssh/id_rsa" &>/dev/null
    fi
    # Check if id_ed25519 exists and add it
    if [ -f "$HOME/.ssh/id_ed25519" ]; then
        ssh-add "$HOME/.ssh/id_ed25519" &>/dev/null
    fi
    # Add other keys if needed, e.g., ssh-add ~/.ssh/my_other_key &>/dev/null
fi

Save the file and then either open a new terminal session or source your .bashrc file:

source ~/.bashrc

Now, when you open a new terminal, ssh-agent should start (if not already running) and attempt to add your keys automatically. You might still be prompted for a passphrase the first time a key is added in a new environment, but it will be managed by the agent thereafter.

For server environments or CI/CD pipelines, ssh-agent persistence is typically handled differently. CI/CD runners often have mechanisms to inject SSH keys securely, or you might start ssh-agent as part of a script for a non-interactive user. Avoid adding ssh-add with passphrases to automated scripts without proper secret management.

By systematically following these steps, you should successfully resolve the "Git error permission denied publickey SSH key agent missing" issue and ensure smooth, passphrase-free Git operations on your CentOS Stream or Rocky Linux system.