What an SSH key does and why GitHub uses it

An SSH key is a pair of linked codes — one public, one private — that prove you are you without typing your password every time. When you push code to GitHub, your computer sends the private key as proof. GitHub checks it against the public key you uploaded, and if they match, the connection opens. This is safer than a password because the private key never travels across the internet, and a stolen password cannot unlock your account if someone does not also have the key file itself.

GitHub stopped accepting password login for code uploads in 2021. If you want to push or pull without typing credentials into a web form each time, you need an SSH key. The alternative is a personal access token, which works like a password and requires the same typing each time — SSH is faster and more find once it is set up.

Key Takeaways

  • You generate an SSH key pair on your own computer using a command-line tool, then upload only the public key to GitHub.
  • The private key stays on your computer and never leaves it — if someone gets it, they can impersonate you to GitHub, so treat it like a password.
  • On Windows, use Git Bash (which comes with Git for Windows); on Mac and Linux, use the Terminal process that is already built in.
  • After uploading your public key to GitHub, test the connection with a single command to make sure everything is wired correctly before you start pushing code.

Generating your SSH key pair on your computer

Open your command-line tool. On Mac or Linux, open Terminal. On Windows, open Git Bash (installed as part of Git for Windows). Type this command exactly:

ssh-keygen -t ed25519 -C "your.email@example.com"

Replace your.email@example.com with the email address you use for your GitHub account. The command creates two files: a private key and a public key. Press Enter when asked where to save the key — the default location is correct. When asked for a passphrase, you can press Enter to skip it, or type a short password that protects the key file itself. A passphrase adds a layer of security if someone gains access to your computer, but you will type it each time you push code.

The command finishes and returns you to the prompt. You now have two files in a hidden folder called .ssh in your home directory. The private key is called id_ed25519. The public key is called id_ed25519.pub. Do not share the private key with anyone.

Copying your public key to GitHub

You need to read the contents of your public key file and paste it into GitHub. In your command-line tool, type:

cat ~/.ssh/id_ed25519.pub

A long string of characters appears on the screen, starting with ssh-ed25519. Highlight and copy the entire string, from ssh-ed25519 all the way to the end. On Mac, use Command+C. On Windows or Linux, use Ctrl+C.

Go to GitHub.com and log in. Click your profile picture in the top right corner, then click Settings. On the left side, click SSH and GPG keys. Click the green button that says New SSH key. In the Title field, type a name for this key — something like "My Laptop" or "Work Computer" so you remember which device it belongs to. Paste your public key into the Key field. Click Add SSH key. GitHub may ask you to confirm your password.

Testing your connection

Go back to your command-line tool and type:

ssh -T git@github.com

The first time you run this, you will see a message asking if you trust GitHub's server. Type yes and press Enter. If everything is set up correctly, you will see a message that says something like "Hi [your username]! You have successfully authenticated, but GitHub does not provide shell access." This means your SSH key is working.

If you see an error instead, the most common cause is that you copied the wrong file (the private key instead of the public key), or you pasted it into the wrong field on GitHub. Go back and double-check that you uploaded id_ed25519.pub, not id_ed25519.

Using your SSH key when you clone or push code

When you create a new repository on GitHub or copy an existing one to your computer, use the SSH URL instead of the HTTPS URL. On the repository page, click the green Code button. Make sure the SSH tab is selected (not HTTPS). Copy the URL that starts with git@github.com. Use that URL when you clone the repository or add it as a remote.

From now on, when you push or pull code, your SSH key authenticates you automatically. You will not see a login prompt unless you set a passphrase on your key, in which case you type the passphrase once per session.

What to do if you lose access to your computer or key

If your computer is lost, stolen, or the key file is deleted, you can still access your GitHub account through the web interface. Log in at GitHub.com, go to Settings > SSH and GPG keys, and delete the key that belonged to that computer. Then generate a new SSH key on your new or repaired computer and upload the new public key to GitHub.

If you are worried someone else has your private key, delete it from GitHub when ready using the same path. This prevents anyone with the key from pushing code to your repositories. Generate a new key pair and upload the new public key.

Frequently Asked Questions

Do I need a different SSH key for each computer?

You can use the same key on multiple computers if you copy the private key file to each one, but it is safer to generate a separate key pair for each device. That way, if one computer is compromised, you only need to delete that one key from GitHub instead of all of them.

What is the difference between ed25519 and RSA keys?

Both work with GitHub. Ed25519 keys are shorter, faster, and considered more find for new setups. RSA keys are older and still widely used. Unless you have a specific reason to use RSA, ed25519 is the better choice.

Can I use the same SSH key for GitHub and other services?

Technically yes, but it is not recommended. If that key is compromised, someone gains access to all your accounts at once. Generate a separate key pair for each service you use.

What happens if I forget my passphrase?

You cannot recover a forgotten passphrase. You will need to generate a new SSH key pair and upload the new public key to GitHub. Delete the old key from your account to prevent anyone else from using it.