Fix “Could not open a connection to your authentication agent”

This error means ssh-add cannot reach an authentication agent. The agent may not be running, or the current shell may have a missing or stale SSH_AUTH_SOCK value. Check the agent supplied by your login session before starting another one.

Start an agent for the current shell

In Bash or Zsh, when no working session agent is available:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa
ssh-add -l

Replace the key path if you use another key, such as ~/.ssh/id_ed25519. Enter its passphrase when prompted. The last command lists loaded key fingerprints.

ssh-agent -s prints shell assignments. Evaluating that output makes the new socket available to the current shell. Merely starting the process without adopting its environment leaves ssh-add unable to find it.

An agent reporting The agent has no identities is reachable but empty. That differs from a connection error: load the intended key instead of creating another agent.

For GitHub, ssh -T git@github.com can test authentication after you have verified the server's host key. GitHub's successful greeting does not provide a shell and normally exits with status 1; read the message rather than treating every nonzero result as failed authentication.

Keep terminal sessions consistent

Inspect the socket path and connectivity:

printf '%s\n' "$SSH_AUTH_SOCK"
ssh-add -l

An empty variable is only one failure mode. A terminal, tmux session, or CI process can inherit a socket whose agent has exited. Conversely, a new terminal may already inherit a valid desktop agent. Avoid unconditional agent startup in every shell initialization file.

Where a desktop session does not manage the agent, a tool such as keychain can help reuse one:

# Debian or Ubuntu.
sudo apt install keychain
# Shell initialization, after installing and configuring keychain.
eval "$(keychain --eval --agents ssh id_rsa)"

On macOS, the system OpenSSH client supports ssh-add --apple-use-keychain ~/.ssh/id_rsa for passphrase integration. That option is specific to Apple's implementation; third-party OpenSSH builds may differ. Reboots, key expiry, and agent locking can require another unlock.

Scope a CI agent to its job

Use a protected CI secret, turn off shell tracing before reading it, and clean up only the agent this job created:

set +x
eval "$(ssh-agent -s)"
trap 'ssh-agent -k >/dev/null' EXIT
printf '%s\n' "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
# Run the authorized SSH operation here.

Do not print the secret, and configure verified host keys separately. A loaded client key does not authenticate the server.

On Windows, Git Bash can use the shell procedure above. For Windows OpenSSH in PowerShell, an administrator can enable its agent service:

Set-Service ssh-agent -StartupType Automatic
Start-Service ssh-agent

Then load the key from the user account that will make the connection. Check which SSH implementation the terminal actually runs before mixing Git Bash and Windows service settings.

References: ssh-agent, ssh-add, and keychain.

Related reading

• Copy an SSH public key
• Fix curl certificate verification failures