Add an SSH Key to GitHub

Using SSH with GitHub is more secure and convenient than typing your password for every push/pull. This tutorial gives a polished, copy-paste friendly, step-by-step workflow (with troubleshooting, tips, and examples) so you can set up SSH keys correctly.

---

Prerequisites

• A terminal on your Linux/macOS machine (or Git Bash on Windows).
• ssh installed (most systems already have it).
• A GitHub account and access to Settings → SSH and GPG keys.

---

Step 1 — Generate SSH Key

Use Ed25519 when generating a new SSH key (recommended)

Run this (replace the email with one you control):

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

How to answer the prompts:

• When asked Enter a file in which to save the key, press Enter to accept the default (~/.ssh/id_ed25519).
• For a passphrase: recommended for extra security — enter one if you want. Press Enter twice to leave it empty (not recommended).

tip

If you already have a key named id_ed25519, consider using a different filename (e.g., id_ed25519_work) to keep devices/accounts separate.

Step 2 — Add to the SSH agent

Optional

keeps you from retyping passphrase

Start the agent and add the key:

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

If you're on macOS and want keys stored in the keychain:

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

To check keys currently loaded:

ssh-add -l

---

Step 3 — Copy the public key to your clipboard

Print the public key:

cat ~/.ssh/id_ed25519.pub

Copy the entire single-line output that begins with ssh-ed25519 ... [email protected].

Shortcuts for copying to clipboard:

• macOS:
  pbcopy < ~/.ssh/id_ed25519.pub
• Linux (X11):
  xclip -sel clip < ~/.ssh/id_ed25519.pub
• Windows (Git Bash):
  clip < ~/.ssh/id_ed25519.pub

---

Step 4 — Add the SSH key to GitHub (GUI)

1. Open GitHub → Settings (top-right profile menu).
2. In the sidebar choose SSH and GPG keys.
3. Click New SSH key (or Add SSH key).
4. Title: give a descriptive name (e.g., Spare Laptop, Work MacBook).
5. Key: paste the contents of ~/.ssh/id_ed25519.pub.
6. Click Add SSH key and confirm your GitHub password if prompted.

---

Step 5 — Test the connection

Quick test:

ssh -T [email protected]

Expected success message:

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

If you want verbose debug output:

ssh -vT [email protected]

---

Common troubleshooting

• Permission denied (publickey)
  • Ensure the public key on GitHub matches ~/.ssh/id_ed25519.pub.
  • Make sure the key is loaded with ssh-add -l. If not, run ssh-add ~/.ssh/id_ed25519.
  • Check file permissions:

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

• SSH uses the wrong key
  Create/Edit ~/.ssh/config:

# Default GitHub SSH config
Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes

# Personal GitHub account
Host github-personal
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_personal
    IdentitiesOnly yes

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

Then clone/push using the host alias:
git clone git@github-work:org/repo.git

• Key not found when testing remotely
  Confirm you’re using the same user on the machine where the key is stored, and verify ~/.ssh path.

Key management: rotate and remove

• Remove a key from GitHub: Settings → SSH and GPG keys → Delete the key.

• Remove locally:

  rm ~/.ssh/id_ed25519*

• Rotate keys: generate a new key, add it to GitHub, test, then remove the old key when satisfied.

---

Security recommendations

• Use a passphrase for private keys if possible.
• Use different keys per device/account.
• Keep private keys (~/.ssh/id_*) secret and never commit them to a repo.
• Periodically review GitHub SSH keys and remove unused ones.

---

Quick reference (copy-paste cheatsheet)

Generate -> add agent -> copy -> add to GitHub -> test:

ssh-keygen -t ed25519 -C "[email protected]"
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
cat ~/.ssh/id_ed25519.pub   # copy this

# (paste into GitHub > Settings > SSH and GPG keys)
ssh -T git@github.com