# How to set up SSH keys

SSH keys let you log in to servers and push to Git hosts without typing a password. A lot of people get this working by copying commands from somewhere and end up with old key types, no passphrase, or the wrong file permissions. This guide goes through doing it properly.

## What you need

- A terminal (macOS, Linux, or Windows 10/11 with OpenSSH, which is installed by default)
- Access to the server or Git host you want to connect to

## Step 1: Check for existing keys

Run `ls -al ~/.ssh`. If you see `id_ed25519` and `id_ed25519.pub` you already have a key and you might not need to make another one. If you only see `id_rsa`, it's probably an older key and you may want to make a new Ed25519 one.

## Step 2: Generate a key

```
ssh-keygen -t ed25519 -C "you@example.com"
```

Press Enter to accept the default location. When it asks for a passphrase, set one. The comment after `-C` is just a label so you can recognise the key later.

## Step 3: Add the key to the agent

The agent remembers your passphrase so you don't have to type it each time.

```
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
```

On macOS add `--apple-use-keychain` to `ssh-add` to store the passphrase in Keychain.

## Step 4: Copy the public key to where it's needed

- For a server: `ssh-copy-id user@host`
- For GitHub/GitLab: paste the contents of `~/.ssh/id_ed25519.pub` into the SSH keys page in your account settings

Never copy the file without `.pub`. That's the private key.

## Step 5: Test it

`ssh -T git@github.com` for GitHub, or `ssh user@host` for a server.

## Common mistakes

| Mistake | What happens | Fix |
| --- | --- | --- |
| Using RSA 1024 or DSA keys | Modern servers refuse them | Generate an Ed25519 key |
| Private key permissions too open | SSH ignores the key with "UNPROTECTED PRIVATE KEY FILE" | `chmod 600 ~/.ssh/id_ed25519` and `chmod 700 ~/.ssh` |
| No passphrase | Anyone who copies the file can use it | Set one with `ssh-keygen -p -f ~/.ssh/id_ed25519` |
| Pasting the private key into GitHub | Your key is compromised | Delete it, generate a new pair, paste the `.pub` |
| Wrong key offered when you have several | "Permission denied (publickey)" | Add a `Host` block with `IdentityFile` in `~/.ssh/config` |
