How to generate SSH keys for GitHub

Create an SSH key with ssh-keygen, add it to your GitHub account, test it with ssh -T and push and pull without typing a password again.

5–8 minutes
Laptop screen showing code beside a keyboard

To use SSHSSH A secure way to type commands on a server from your own computer, as if you were sitting at it. More about SSH → keys with GitHub, you create a key pair on your own computer, paste the public half into your GitHub settings, and tell Git to use an SSH address for your repositories. This guide is for anyone who pushes code to GitHub from Windows, macOS or Linux, including from a web server that pulls a site’s code.

Run ssh-keygen -t ed25519 -C “you@example.com” and accept the default file location. Copy the contents of ~/.ssh/id_ed25519.pub, then in GitHub go to Settings, SSH and GPG keys, New SSH key and paste it in as an Authentication Key. Test with ssh -T git@github.com: a message saying you have successfully authenticated means it works.

Why use an SSH key for GitHub

GitHub does not accept your account password when Git pushes or pulls code. You need either a personal access token over HTTPSHTTPS The secure version of the web, shown by the padlock. Everything sent between you and the site is scrambled so nobody in between can read or change it. More about HTTPS → or an SSH key. An SSH key is set up once per computer and then works silently.

A key pair is two files. The private key (id_ed25519) stays on your computer and must never be shared or uploaded anywhere. The public key (id_ed25519.pub) is safe to give out, and that is the half GitHub stores. When Git connects, GitHub checks that your computer holds the private key that matches. If SSH or key pairs are new to you, What is SSH? explains the idea in more depth.

You can use the same key for GitHub and for logging in to your own servers, but many people make one key per computer and add it to every service that computer needs.

Step 1: check for an existing key

You may already have a key. Open a terminal (Terminal on macOS and Linux; PowerShell or Git Bash on Windows) and list your SSH folder:

ls ~/.ssh

If you see id_ed25519 and id_ed25519.pub, you already have a key and can skip to step 3. If the folder does not exist or holds only known_hosts, carry on.

Step 2: generate a new key

Run this, using the email address on your GitHub account. The -C part is only a label (a comment) inside the key so you can recognise it later:

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

-t ed25519 picks the Ed25519 key type, which is short, fast and the type GitHub recommends. Then answer the prompts:

  1. Enter file in which to save the key: press Enter to accept the default, ~/.ssh/id_ed25519. On Windows this is C:\Users\exampleco\.ssh\id_ed25519.
  2. Enter passphrase: type a passphrase and press Enter, then type it again. A passphrase encrypts the private key, so a stolen laptop does not mean a stolen GitHub account. Step 5 shows how to avoid typing it every time.

Success looks like a message that your identification and public key have been saved, followed by a key fingerprint starting SHA256: and a small block of ASCII art.

If you need to connect from a very old system that does not understand Ed25519, use ssh-keygen -t rsa -b 4096 -C "you@example.com" instead. The files are then called id_rsa and id_rsa.pub.

Step 3: add the public key to GitHub

First copy the public key. Make sure the file name ends in .pub.

SystemCommand to copy the public key
macOSpbcopy < ~/.ssh/id_ed25519.pub
Windows (Git Bash)clip < ~/.ssh/id_ed25519.pub
Windows (PowerShell)Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub then select and copy the line
Linuxcat ~/.ssh/id_ed25519.pub then select and copy the line

The key is one long line starting ssh-ed25519 and ending with your email label. Then, in GitHub:

  1. Click your profile picture in the top right and choose Settings.
  2. In the Access section of the sidebar, click SSH and GPG keys.
  3. Click New SSH key.
  4. Give it a Title that names the computer, such as “Work laptop” or “web serverWeb server The program that answers visitors’ browsers and sends them your website. Also used for the computer it runs on. More about Web server → example.com”.
  5. Leave Key type set to Authentication Key.
  6. Paste the key into the Key box and click Add SSH key. GitHub may ask you to confirm your password or two-factor code.

Never paste the private key (the file without .pub) into GitHub or anywhere else. If you ever do, delete that key from GitHub at once and generate a new pair.

Step 4: test the connection

ssh -T git@github.com

The first time, SSH shows GitHub’s host key fingerprint and asks whether to continue. GitHub’s Ed25519 fingerprint is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU. If it matches, type yes. SSH records it in ~/.ssh/known_hosts and will warn you if it ever changes.

Success looks like this:

Hi exampleco! You've successfully authenticated, but GitHub does not provide shell access.

The second half is normal. GitHub lets Git in over SSH but never gives you a command line on its servers.

Step 5: stop typing the passphrase every time

An SSH agent is a small background program that holds your unlocked key in memory, so you type the passphrase once per session rather than on every push.

macOS

Create or edit ~/.ssh/config and add:

Host github.com
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519

Then add the key once, saving the passphrase in your macOS keychain:

ssh-add --apple-use-keychain ~/.ssh/id_ed25519

Windows

Windows includes an OpenSSH agent service that is switched off by default. Open PowerShell as administrator and run:

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

Then, in a normal PowerShell window:

ssh-add $env:USERPROFILE\.ssh\id_ed25519

Linux

Most desktop Linux systems start an agent when you log in. Add the key with:

ssh-add ~/.ssh/id_ed25519

On a server with no desktop, start an agent for the current session first with eval "$(ssh-agent -s)".

Step 6: use SSH addresses for your repositories

A key only helps if Git uses an SSH address. On a repository’s GitHub page, click Code, choose the SSH tab and copy the address. It looks like git@github.com:exampleco/example-site.git.

To clone a new repository:

git clone git@github.com:exampleco/example-site.git

To switch an existing repository that was cloned over HTTPS, go into its folder and run:

git remote set-url origin git@github.com:exampleco/example-site.git
git remote -v

The second command should now show the git@github.com: address for both fetch and push.

Common problems

SymptomCauseFix
Permission denied (publickey)GitHub does not have the public key, or SSH is offering a different keyCheck the key is listed under SSH and GPG keys. Run ssh -vT git@github.com and look for which key file is offered.
Git still asks for a username and passwordThe repository remote is an HTTPS addressRun git remote set-url with the SSH address as in step 6.
Key is already in use when adding itThe same key is attached to another GitHub account or as a deploy keyGenerate a separate key for this account, or remove it from the other place first.
Connection times out on port 22A firewall or office network blocks the SSH portUse GitHub’s SSH over port 443: see the config below.
Bad configuration option: usekeychainUseKeychain is a macOS-only optionRemove it on Linux and Windows, or add IgnoreUnknown UseKeychain above it.
Error connecting to agent on WindowsThe ssh-agent service is not runningRun the administrator commands in step 5.

If portPort A numbered door on a server. Each service listens behind its own door: web pages on 443, email on others, remote login on 22. More about Port → 22 is blocked, add this to ~/.ssh/config. GitHub accepts SSH on port 443 at the host name ssh.github.com:

Host github.com
  Hostname ssh.github.com
  Port 443
  User git

Test again with ssh -T git@github.com.

Official documentation

Get the next guide

One email when there is something worth reading: new guides, errors going around, and hosting changes that affect your site.

No tracking pixels, and one click to leave.

Something out of date? Software changes. If a step no longer works, tell us and we will check it and update the page.