Setting up an SSH key for GitHub or a server

An SSH key lets you sign in to a server, or push to GitHub, GitLab or Bitbucket, without typing a password. It’s a pair of files: a private key that stays on your computer, and a public key you hand out. Most problems come from the in-between steps: the wrong file uploaded, permissions the ssh command refuses, or not knowing which of several keys a site has.

Take care with secrets. This runs only in your browser: what you enter isn't uploaded, stored or put in a link, and the page is built so that it can't send it anywhere else. Your browser's extensions and other software on your device can still see what's on screen, so use a device you trust and real secrets only when you need to. Disconnecting from the internet once the page has loaded gives the most protection. Use is at your own risk: see the terms.

1. Make the key pair

On a Mac, Linux or Windows 10 and later, ssh-keygen -t ed25519 in a terminal makes the pair and asks for a passphrase. When a terminal isn’t to hand, or you’d rather see what you’re getting, use the SSH Key Generator: leave Key type on Ed25519 (best for most uses), type a Comment such as alice@laptop to tell your keys apart, and press Make a key pair. Choose RSA 4096-bit (older servers) only for a server that refuses Ed25519.

Save both files into the .ssh folder in your home folder: the private key as id_ed25519 and the public key as id_ed25519.pub. The private key is saved without a passphrase, so add one straight away with the second command under Then, in a terminal (ssh-keygen -p -f ~/.ssh/id_ed25519). Anyone who gets a copy of the file then also needs the passphrase.

2. Give the public key to GitHub or the server

Only ever hand out the .pub file, the one line starting ssh-ed25519. The private key never leaves your computer.

• GitHub: Settings › SSH and GPG keys › New SSH key, then paste the line. GitLab and Bitbucket have the same page under your profile’s settings. Test it with ssh -T git@github.com, which answers with your user name.
• A server: ssh-copy-id -i ~/.ssh/id_ed25519.pub user@server (the third command the generator gives) adds it for you. Without ssh-copy-id, sign in another way and add the line to the end of ~/.ssh/authorized_keys on the server.

The first time you connect, ssh shows the server’s own fingerprint and asks whether to trust it. For GitHub, compare it with the fingerprints GitHub publishes in its documentation; for your own server, with what its administrator or hosting control panel shows. Answer yes only when they match.

3. Fix “permissions are too open”

ssh refuses a private key that other users could read, with an error such as Permissions 0644 for ‘/Users/you/.ssh/id_ed25519’ are too open … This private key will be ignored. The same strictness on the server side makes it ignore an authorized_keys file others can change, and fall back to asking for a password.

In Permissions, type 600 in Octal to see it means rw-------, read and write for you only, and copy the command. The usual set is:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519 ~/.ssh/authorized_keys
chmod 644 ~/.ssh/id_ed25519.pub

Run the same commands on the server if signing in still asks for a password. On Windows, permissions work differently: if ssh complains there, the key file’s Properties › Security must list only your own account.

4. Choose the key for each host

With several keys, or two GitHub accounts, ssh tries every key it has in turn, and a server may accept the wrong one or give up after too many. Tell it which key goes with which host in ~/.ssh/config:

Host github-work
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_work
  IdentitiesOnly yes

Then use the short name in place of the real one, as in git clone git@github-work:company/project.git. IdentitiesOnly yes stops ssh offering keys the file doesn’t name.

Paste the whole file into the SSH Config Inspector and type github-work to see the settings it gets and the line each comes from. ssh keeps the first value it finds for most settings but uses every IdentityFile that applies, in order, so an IdentityFile under Host * near the top is tried first. The Inspector lists them in the order they’re tried and warns when a Host * block above overrides a later one.

5. Which key is which?

After a few years there are several keys on your computer and several on GitHub, and it’s hard to tell which to remove. GitHub lists each key with its SHA-256 fingerprint. Paste a .pub line into the Certificate Decoder and it shows the key’s type, size, comment and SHA-256 fingerprint to compare. Remove any key on the site that matches none of yours, and any key for a computer you no longer have.

If you also sign commits or email with PGP, the PGP Key Viewer shows a PGP key’s fingerprint, user IDs and expiry in the same way. Before trusting a PGP key someone sent you, compare its fingerprint with them by another route, such as a call.