SSH Key

When you push to or pull from a remote repository over SSH (for example a [email protected]:... URL), Git needs to prove who you are without typing a password every time. SSH keys solve this. This chapter explains what an SSH key is, how the key pair works, and how to generate one and register it with a remote on macOS, Linux, and Windows.

What are SSH Keys?

An SSH key is an access credential used in the SSH protocol (Secure Shell). SSH is a network protocol that lets you log in from one computer to another securely, and manage servers, operating systems, and configurations over an encrypted connection. Functionally, SSH keys play the same role as a password, but they are far more secure: the key is never sent over the network, and deriving the private key from the public key is computationally infeasible.

SSH keys always come in pairs, and each pair is composed of a public key and a private key:

1. Public key (also called the authorized key). You share this freely and add it to each system you want to access. It determines who is allowed in.
2. Private key (also called the identity key). This stays secret on your machine and must never be shared. It proves your identity to any server that holds the matching public key.

The two are mathematically linked. A server encrypts a challenge with your public key; only the holder of the matching private key can answer it. That is how authentication happens without ever transmitting a secret.

Why use SSH keys with Git

• No password on every push. Once the key is registered, git push, git pull, and git fetch over SSH authenticate silently.
• Stronger than passwords. Keys cannot be guessed or brute-forced the way short passwords can.
• Required by many hosts. GitHub no longer accepts account passwords for Git operations; SSH keys (or tokens) are the standard.

To clone a repository with SSH after your key is set up, use the git@ form of the URL. See Git Clone and Git Remote for how remotes are addressed.

How To Set Up SSH Keys?

You generate SSH keys with a key generation tool, almost always ssh-keygen, which ships with the OpenSSH client. It uses public-key cryptographic algorithms; the most common are Ed25519 (modern, short, fast, recommended) and RSA. Older algorithms such as DSA exist but are now considered weak and are disabled by default in current OpenSSH.

The -t flag selects the algorithm. Two common choices:

# Recommended: Ed25519
ssh-keygen -t ed25519 -C "[email protected]"

# Compatibility fallback: RSA with a 4096-bit key
ssh-keygen -t rsa -b 4096 -C "[email protected]"

The -C flag adds a comment (typically your email) so the key is easy to identify in a list of authorized keys.

Create an SSH key on Mac and Linux

Both operating systems ship with a modern terminal and the OpenSSH package, so the steps are identical.

1. Open a terminal and run:

Generate the key pair

ssh-keygen -t ed25519 -C "[email protected]"

2. Choose where to save the key. Press Enter to accept the default location (~/.ssh/id_ed25519):

Choose the file location

> Enter a file in which to save the key (~/.ssh/id_ed25519): [Press enter]

This creates two files: the private key id_ed25519 and the public key id_ed25519.pub.

3. Set a passphrase. This encrypts the private key on disk, so even a stolen key file is useless without it. You will be asked for it whenever the key is first used in a session:

Set a passphrase

> Enter passphrase (empty for no passphrase): [Type a passphrase]
> Enter same passphrase again: [Type passphrase again]

4. Add the new SSH key to the ssh-agent. The ssh-agent holds your decrypted private keys in memory and signs authentication requests on your behalf, so you only type the passphrase once per session.

Execute the following command to make sure that the ssh-agent is running:

SSH Key on Linux

eval "$(ssh-agent -s)"
> Agent pid 59566

If the ssh-agent is running, add the new SSH key to the local SSH agent by executing the following command:

SSH Key

ssh-add ~/.ssh/id_ed25519

(Note: On modern macOS (OpenSSH 8.8+), ssh-add -K is deprecated. Instead, add AddKeysToAgent yes to your ~/.ssh/config file to automatically persist keys in the keychain.)

5. Copy the public key to the remote server. To use the key for authentication, you must add it to the remote server's ~/.ssh/authorized_keys file. Run the following command from your local machine:

ssh-copy-id -i ~/.ssh/id_ed25519.pub user@remote_host

6. Verify the connection. Test that you can log in to the remote server using your new key:

ssh user@remote_host

Create an SSH Key on Windows

You need Git Bash to create an SSH key on the Windows operating system. Open Git Bash and run the following command to generate the key:

ssh-keygen -t ed25519 -C "[email protected]"

Follow the same prompts as above to set the file location and passphrase. After generating the key, copy it to your remote server or Git hosting service using the ssh-copy-id command, or by pasting the contents of id_ed25519.pub into the service's SSH key settings.

Add Your Key to GitHub, GitLab, or Bitbucket

A Git host is not an SSH server you control, so ssh-copy-id does not apply — you paste the public key into the web UI instead. Print the public key and copy it:

cat ~/.ssh/id_ed25519.pub

The output is a single line that starts with ssh-ed25519 and ends with the comment you set:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... [email protected]

Copy that whole line and add it under your account's SSH key settings (on GitHub: Settings → SSH and GPG keys → New SSH key). Then verify the connection:

ssh -T [email protected]

A successful first connection asks you to confirm the host fingerprint and then greets you by username — it does not open a shell, which is expected for GitHub.

Once the key is registered, switch your remote to the SSH URL so pushes use it:

git remote set-url origin [email protected]:user/repo.git

See Git Remote for managing remote URLs and Git Push for sending your commits.

Common Issues and Tips

• Permission denied (publickey) usually means the host has no matching public key, or the agent does not hold your private key. Run ssh-add -l to list loaded keys and re-add yours if needed.
• Reuse one key across hosts. A single key pair can authenticate to many servers; you do not need a new key per project. Generate a separate key only when you want to isolate access.
• Back up your keys, not just your repos. Losing ~/.ssh/id_ed25519 means regenerating and re-registering everywhere.
• SSH keys authenticate connections; if you also want to prove who authored a commit, that is a separate mechanism — see Signing Commits. For first-time setup, see Install Git and Git Config.

Practice