How To Add an SSH Key to GitHub (Step‑By‑Step Guide)

Adding an SSH key to GitHub lets you connect to your repos securely without typing your username and password every time. It’s faster, safer, and the standard way most developers work with GitHub from their laptop or desktop.

This guide walks you through what SSH keys are, why GitHub uses them, and how to add one to your account—plus the ways the process can differ depending on your system.

What is an SSH Key and Why Does GitHub Need It?

SSH (Secure Shell) is a protocol for securely connecting to another computer over a network. Instead of using a password each time, SSH can use a key pair:

• A public key – safe to share; you upload this to GitHub
• A private key – stays on your device; never share this with anyone

When you run a Git command like git push over SSH:

1. GitHub checks if your account has a public key on file.
2. Your computer proves it holds the matching private key (cryptographically).
3. If they match, GitHub lets you in without requiring a password.

This gives you:

• Security: Long, hard‑to‑guess keys instead of reused passwords.
• Convenience: No constant password prompts.
• Automation: Scripts and tools can access repos securely without storing plaintext passwords.

Overview: Steps to Add an SSH Key to GitHub

At a high level, you’ll:

1. Check if you already have an SSH key on your computer.
2. Generate a new SSH key pair if needed.
3. Add the key to your SSH agent (so your OS can use it automatically).
4. Copy the public key.
5. Add it to GitHub in your account settings.
6. Test the connection.

Each step is the same idea across operating systems, but the commands and tools vary slightly.

Step 1: Check If You Already Have an SSH Key

On macOS and Linux

Open Terminal and run:

ls -al ~/.ssh 

Look for files like:

• id_ed25519 and id_ed25519.pub
• or id_rsa and id_rsa.pub

The file ending in .pub is your public key. The other is your private key.

If you see an existing pair you know you created for GitHub before, you might reuse it. If you’re unsure or it’s from an old setup, generating a fresh key is usually cleaner.

On Windows (Git Bash or PowerShell)

Using Git Bash:

ls -al ~/.ssh 

Using PowerShell:

Get-ChildItem -Path $env:USERPROFILE.ssh 

Again, look for id_ed25519(.pub) or id_rsa(.pub).

If no .ssh folder or key files exist, you’ll need to create them.

Step 2: Generate a New SSH Key Pair

GitHub currently recommends ED25519 keys when possible. If your system doesn’t support ED25519, you can fall back to RSA.

Recommended: Generate an ED25519 key

Run this in Terminal (macOS/Linux) or Git Bash/PowerShell (Windows, with Git installed):

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

• Replace [email protected] with the email tied to your GitHub account.
• If you see an error like unknown key type ed25519, your OpenSSH is older; use RSA instead (see below).

You’ll be prompted:

• “Enter file in which to save the key” – press Enter to accept the default (~/.ssh/id_ed25519).
• “Enter passphrase” – optional but strongly recommended.
  • A passphrase encrypts your private key on disk.
  • If you set one, the SSH agent can remember it so you don’t type it constantly.

Alternative: Generate an RSA key

If ED25519 isn’t available:

ssh-keygen -t rsa -b 4096 -C "[email protected]" 

Same prompts: file location and optional passphrase.

After this step, you should have:

• ~/.ssh/id_ed25519 and ~/.ssh/id_ed25519.pub
  or
• ~/.ssh/id_rsa and ~/.ssh/id_rsa.pub

Step 3: Add Your Key to the SSH Agent

The SSH agent is a small background program that stores your private key and handles authentication for you.

Start the SSH agent

macOS and Linux:

eval "$(ssh-agent -s)" 

You should see output like Agent pid 12345.

Windows (Git Bash):

eval "$(ssh-agent -s)" 

Windows (PowerShell with OpenSSH Client installed):

Start-Service ssh-agent Get-Service ssh-agent 

Add your SSH private key to the agent

If you generated an ED25519 key:

ssh-add ~/.ssh/id_ed25519 

For RSA:

ssh-add ~/.ssh/id_rsa 

If you set a passphrase, you’ll enter it now. The agent remembers it for your current session (and sometimes across reboots depending on OS and configuration).

Step 4: Copy Your Public Key

You must copy the public key file—the one ending in .pub.

macOS

pbcopy < ~/.ssh/id_ed25519.pub 

or for RSA:

pbcopy < ~/.ssh/id_rsa.pub 

This copies the key to your clipboard.

Linux

Use xclip or xsel (install if needed):

xclip -selection clipboard < ~/.ssh/id_ed25519.pub 

Or, if those aren’t available, you can print it and copy manually:

cat ~/.ssh/id_ed25519.pub 

Then select and copy the whole line (including ssh-ed25519 or ssh-rsa and your email).

Windows

Git Bash:

clip < ~/.ssh/id_ed25519.pub 

Or:

clip < ~/.ssh/id_rsa.pub 

PowerShell:

Get-Content $env:USERPROFILE.sshid_ed25519.pub | Set-Clipboard 

If that doesn’t work, output the key and copy it:

Get-Content $env:USERPROFILE.sshid_ed25519.pub 

Step 5: Add the SSH Key to Your GitHub Account

1. Sign in to GitHub in your browser.
2. Click your profile picture (top right) → Settings.
3. In the left sidebar, click SSH and GPG keys.
4. Click New SSH key (or Add SSH key).
5. In Title, enter something descriptive:
   • e.g., MacBook Pro, Work PC, Home Desktop.
6. In Key, paste the public key you copied earlier.
   • It should start with ssh-ed25519 or ssh-rsa and end with your email.
7. Click Add SSH key.
8. If prompted, confirm with your GitHub password or 2FA.

GitHub now associates that device’s SSH key with your account.

Step 6: Test Your SSH Connection to GitHub

Back in your terminal, run:

ssh -T [email protected] 

The first time you connect, you may see something like:

The authenticity of host 'github.com (IP address)' can't be established.
Are you sure you want to continue connecting (yes/no)?

Type:

yes 

If everything is set up correctly, you’ll see:

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

That message is expected—GitHub is confirming your SSH key works, not giving you a shell.

Using SSH with Existing or New Git Repos

Clone using SSH

When you clone a repo, choose the SSH option on GitHub and use the URL that looks like:

git clone [email protected]:username/repository.git 

Now git pull and git push will use your SSH key for authentication.

Switch an existing repo from HTTPS to SSH

If you initially cloned using HTTPS, you can switch the remote:

1. Check current remote:

   git remote -v 

2. Set the SSH URL (use your actual repo path):

   git remote set-url origin [email protected]:username/repository.git 

3. Verify:

   git remote -v 

Future pushes and pulls will go over SSH.

Common Variables That Change How This Works

Although the overall process is the same, several factors affect the details:

These variables don’t change what SSH keys are, but they influence how you set them up and maintain them.

Different User Profiles, Different SSH Setups

Because of those variables, adding an SSH key to GitHub can look quite different in practice.

1. Single Personal Laptop, Simple Setup

• OS: macOS or Windows laptop.
• Needs: Clone, edit, push personal projects.
• Likely approach:
  • One ED25519 key pair (id_ed25519).
  • Add to ssh-agent with a passphrase.
  • Use SSH URLs for all GitHub repos.
• Trade‑offs: Easy to manage; minimal complexity; fine for most individuals.

2. Multiple Machines (Work + Personal)

• OS: Mix of work laptop, home desktop, maybe WSL or a Linux box.
• Needs: Access the same GitHub account securely from each device.
• Likely approach:
  • Separate key pair per machine (e.g., id_ed25519_work, id_ed25519_home).
  • Multiple SSH keys added to the same GitHub account, each with a clear label.
• Trade‑offs: More keys to track, but better isolation if one device is lost or compromised.

3. Strict Corporate or Enterprise Environment

• OS: Managed Windows or macOS.
• Needs: Access to GitHub Enterprise or organization repos.
• Likely approach:
  • Keys may require a specific algorithm or length.
  • Passphrases may be mandatory.
  • Some setups require smartcards, security keys, or SSO integration.
• Trade‑offs: Stronger security, but more setup steps and policy constraints.

4. Automation, CI, and Servers

• OS: Linux servers, containers, CI pipelines.
• Needs: Non‑interactive Git operations (deploys, CI checks).
• Likely approach:
  • Dedicated deploy keys for certain repos.
  • Keys stored in CI secure variables or on servers with restricted access.
• Trade‑offs: Convenience vs security; tighter scoping of access becomes crucial.

Where Your Own Situation Becomes the Missing Piece

The basic recipe for adding an SSH key to GitHub is always the same: generate a key, load it into the agent, upload the public half to GitHub, and use SSH URLs. The underlying cryptography and GitHub’s behavior don’t really change.

What does change is how you apply this:

• Which key type makes sense for your OS and SSH version
• How many keys you generate and how you label them
• Whether you lock them with a passphrase, and how often you’re willing to type it
• How you handle keys across work vs personal devices or automated systems

Once you understand the steps, the remaining decisions come down to your own devices, policies, and comfort level with the tools you’re using.