ssh-agent: Usage, Options & Common CI Errors

ssh-agent caches your decrypted SSH keys so commands authenticate without prompts.

ssh-agent lets a pipeline load a deploy key once and have ssh, git, and rsync use it without re-reading the key file. The classic CI mistake is starting the agent in a subshell so SSH_AUTH_SOCK never reaches later steps.

What it does

ssh-agent runs a background process that holds private keys in memory; clients find it via the SSH_AUTH_SOCK environment variable. ssh-add loads keys into it. In CI it provides keys to ssh/git over SSH without exposing the key file to every command or prompting for a passphrase.

Common usage

Terminal

eval "$(ssh-agent -s)"          # start agent, export env into THIS shell
ssh-add ./deploy_key            # load a key
ssh-add - <<< "${SSH_PRIVATE_KEY}"   # load a key from a CI secret
ssh-add -l                      # list loaded key fingerprints
git clone git@github.com:org/repo.git   # uses the agent

Options

Command	What it does
eval "$(ssh-agent -s)"	Start the agent and export its env vars
ssh-add <file>	Add a private key to the agent
ssh-add -	Read a key from stdin (CI secrets)
ssh-add -l	List loaded key fingerprints
ssh-add -D	Remove all loaded keys

Common errors in CI

"Could not open a connection to your authentication agent" means SSH_AUTH_SOCK is unset - you must eval "$(ssh-agent -s)" so the variables export into the current shell, not run ssh-agent in a pipe/subshell where they are lost. Each CI step often gets a fresh shell, so the agent from a prior step is gone; either run agent + ssh-add + the SSH command in one step, or persist SSH_AUTH_SOCK. "ssh-add: ... error in libcrypto" / "invalid format" means a corrupted key (lost newlines from a secret). A passphrase-protected key still prompts under ssh-add unless fed via SSH_ASKPASS or stripped with an empty passphrase.