How to Set Up and Use GitHub SSH: A Step-by-Step Guide
If you're tired of typing your GitHub username and a personal access token every time you push code, SSH is the fix. Once it's set up, git push and git pull just work — no prompts, no tokens to copy-paste, no expiring credentials to renew.
This guide walks through generating an SSH key, adding it to GitHub, and confirming everything works, on Linux or macOS.
What You'll Need
- A terminal (Linux, macOS, or Git Bash/WSL on Windows)
- A GitHub account
- 5 minutes
Step 1 — Check for an Existing SSH Key
You may already have one. Check before generating a new key:
ls -al ~/.ssh
If you see a pair of files like id_ed25519 and id_ed25519.pub, you have a key already and can skip to Step 3. If the directory doesn't exist or is empty, move on to Step 2.
Step 2 — Generate a New SSH Key
GitHub recommends the Ed25519 algorithm — it's faster and just as secure as RSA, with a much shorter key.
ssh-keygen -t ed25519 -C "your_email@example.com"
Replace the email with the one tied to your GitHub account. You'll be prompted for:
- A file location — press Enter to accept the default (
~/.ssh/id_ed25519). - A passphrase — optional, but recommended. It protects your private key if your machine is ever compromised. You'll only need to type it once per session thanks to the SSH agent (next step).
Step 3 — Add Your Key to the SSH Agent
The SSH agent holds your decrypted key in memory so you're not re-entering your passphrase constantly.
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
On macOS, if you want the key to persist across reboots via Keychain:
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
Step 4 — Copy Your Public Key
You need the public key (.pub file) — never the private one.
cat ~/.ssh/id_ed25519.pub
Select and copy the full output, starting with ssh-ed25519 and ending with your email.
On macOS you can copy it directly to the clipboard instead:
pbcopy < ~/.ssh/id_ed25519.pub
On Linux with xclip installed:
xclip -selection clipboard < ~/.ssh/id_ed25519.pub
Step 5 — Add the Key to GitHub
- Log in to GitHub and go to Settings.
- In the sidebar, click SSH and GPG keys.
- Click New SSH key.
- Give it a descriptive title (e.g. "Work Laptop — Pop!_OS 2026") so you can identify it later if you ever need to revoke it.
- Paste your public key into the Key field.
- Click Add SSH key.
Step 6 — Test the Connection
ssh -T git@github.com
The first time you connect, you'll see a fingerprint prompt asking whether to continue — type yes. If everything is configured correctly, you'll see:
Hi your-username! You've successfully authenticated, but GitHub does not provide shell access.
That message means it worked — GitHub doesn't offer an interactive shell over SSH, so seeing that response confirms authentication succeeded.
Step 7 — Clone or Switch a Repo to SSH
For a new repository, use the SSH URL (starts with git@github.com:) instead of the HTTPS one when cloning:
git clone git@github.com:your-username/your-repo.git
For a repo you already cloned over HTTPS, switch its remote to SSH:
git remote set-url origin git@github.com:your-username/your-repo.git
Verify it took effect:
git remote -v
Troubleshooting
"Permission denied (publickey)" — Your key likely isn't loaded in the agent, or isn't linked to your GitHub account. Run ssh-add -l to confirm the key is loaded, and double-check the public key was pasted correctly in GitHub's settings.
Connections blocked on port 22 — Some networks (corporate VPNs, some ISPs) block SSH's default port. GitHub offers a workaround using port 443 — see GitHub's official troubleshooting guide if you hit this.
Using multiple GitHub accounts on one machine — You'll need a separate key per account and a ~/.ssh/config file that maps each account to its own key. That's a bigger topic worth its own post if there's interest — let me know.
Wrap-Up
That's it — SSH authentication set up end to end. It's a five-minute task that saves you from re-authenticating constantly, and it's one of those things worth doing on day one of any new machine setup.