An SSH key is a secure way to prove your identity to GitHub without typing your password every time. GitHub Desktop sets this up automatically, but if you need to add one manually, go to Settings → SSH and GPG keys → New SSH key, paste your public key, and save. This is mainly needed when using Git tools outside of GitHub Desktop.
What SSH Keys Are and When You Need Them
SSH stands for Secure Shell. An SSH key is a pair of files — a private key (kept secret on your computer) and a public key (shared with GitHub). When you connect to GitHub, your computer proves its identity using the private key, and GitHub verifies it against the public key you registered. This means you never have to type your GitHub password when pushing or pulling code.
Important context before you start:
- **GitHub Desktop handles SSH automatically.** If you only use GitHub Desktop to manage your repositories, you likely do not need to set up SSH keys manually. GitHub Desktop uses its own authentication system. - **You need SSH keys when** you use other Git tools (like Cursor's built-in terminal, Replit's shell, or VS Code) that connect to GitHub repositories via the SSH protocol. - **HTTPS vs SSH** are two ways to connect to GitHub. HTTPS uses a username and token. SSH uses key pairs. Both work — SSH is more convenient for frequent use. - **One key pair per computer.** You generate the keys on your computer and upload only the public key to GitHub. The private key never leaves your machine.
This guide covers both the easy path (GitHub Desktop) and the manual path for when you need it.
Prerequisites
- A GitHub account
- GitHub Desktop installed (for the automatic method)
- A computer running macOS or Windows
Step-by-step guide
Check if GitHub Desktop already handles your authentication
Check if GitHub Desktop already handles your authentication
Open **GitHub Desktop** on your computer. Click **GitHub Desktop** in the menu bar (Mac) or **File** (Windows), then select **Preferences** (Mac) or **Options** (Windows). Click the **Accounts** tab. If you see your GitHub username listed under GitHub.com, you are already authenticated. GitHub Desktop uses its own token-based system, and you do not need an SSH key for repositories managed through GitHub Desktop. If you only use GitHub Desktop to push and pull code, you can stop here — no SSH key setup is needed.
Expected result: You see your GitHub account connected in GitHub Desktop's Preferences → Accounts tab.
Generate an SSH key on your computer (Mac)
Generate an SSH key on your computer (Mac)
If you need SSH for another tool, you must generate a key pair. On Mac, open **Launchpad** and search for **Terminal** (or find it in Applications → Utilities). This is the one time we need to use the Terminal app — just for generating the key. In Terminal, type the following and press Enter. Replace the email with your GitHub email address. When asked for a file location, press Enter to accept the default. When asked for a passphrase, you can press Enter twice to skip it (or type a passphrase for extra security). After the command completes, you will see a 'randomart image' — this confirms your key was created.
1ssh-keygen -t ed25519 -C "your-email@example.com"Expected result: Two files are created: ~/.ssh/id_ed25519 (private key) and ~/.ssh/id_ed25519.pub (public key).
Copy the public key to your clipboard
Copy the public key to your clipboard
You need to copy the contents of the public key file (the one ending in .pub). On Mac, in the same Terminal window, type the following command and press Enter. This copies the public key to your clipboard so you can paste it on GitHub. On Windows, the equivalent is: open File Explorer, navigate to C:\Users\YourName\.ssh\, open id_ed25519.pub with Notepad, and copy all the text.
1pbcopy < ~/.ssh/id_ed25519.pubExpected result: The public key text is copied to your clipboard (you will not see any output — that is normal).
Add the SSH key to your GitHub account
Add the SSH key to your GitHub account
Go to **github.com** and sign in. Click your **profile picture** in the top-right corner → **Settings**. In the left sidebar, click **SSH and GPG keys** (under the 'Access' section). Click the green **New SSH key** button. Fill in the form: - **Title**: Give it a descriptive name like 'My MacBook' or 'Work Laptop' so you know which computer this key belongs to. - **Key type**: Leave it as 'Authentication Key.' - **Key**: Click in the text box and paste (Cmd+V on Mac, Ctrl+V on Windows). The text should start with `ssh-ed25519` followed by a long string of characters. Click the green **Add SSH key** button. GitHub may ask you to confirm your password.
Expected result: The SSH key appears in your list of SSH keys on the Settings → SSH and GPG keys page.
Verify the connection works
Verify the connection works
Back in Terminal (Mac) or Command Prompt (Windows), type the following command and press Enter. If everything is set up correctly, you will see a message like: 'Hi yourusername! You have successfully authenticated, but GitHub does not provide shell access.' This confirms your SSH key is working. If you see 'Permission denied (publickey),' double-check that you copied the correct .pub file and that the key on GitHub matches.
1ssh -T git@github.comExpected result: A success message confirming authentication with your GitHub username.
Complete working example
1# SSH Key Setup — Quick Reference23## Do I need SSH?4- Using GitHub Desktop only → NO, skip this5- Using Cursor, VS Code, Replit shell, or terminal → YES67## Mac Setup81. Open Terminal92. ssh-keygen -t ed25519 -C "your-email@example.com"103. Press Enter for defaults114. pbcopy < ~/.ssh/id_ed25519.pub125. GitHub → Settings → SSH keys → New SSH key → paste136. Test: ssh -T git@github.com1415## Windows Setup161. Open Command Prompt or PowerShell172. ssh-keygen -t ed25519 -C "your-email@example.com"183. Press Enter for defaults194. Open C:\Users\You\.ssh\id_ed25519.pub in Notepad → copy205. GitHub → Settings → SSH keys → New SSH key → paste216. Test: ssh -T git@github.com2223## Troubleshooting24- Permission denied → wrong key copied or key not added25- Connection timeout → firewall blocking port 22Common mistakes when adding an SSH Key to GitHub
Why it's a problem: Copying the private key instead of the public key
How to avoid: Always copy the file ending in .pub (e.g., id_ed25519.pub). The private key file has no extension and must never be shared.
Why it's a problem: Adding the SSH key to the wrong GitHub account
How to avoid: Verify you are signed in to the correct GitHub account before adding the key. Check the profile picture → username in the top-right corner.
Why it's a problem: Generating a new SSH key when one already exists
How to avoid: Before generating, check if ~/.ssh/id_ed25519.pub already exists. If it does, you can reuse it — just copy and paste the existing public key to GitHub.
Why it's a problem: Using SSH URL when the tool expects HTTPS (or vice versa)
How to avoid: SSH URLs start with git@github.com:. HTTPS URLs start with https://github.com/. Make sure your tool is configured for the protocol matching your authentication method.
Best practices
- Use GitHub Desktop for most tasks — it handles authentication automatically without SSH keys.
- Give each SSH key a descriptive title (like your computer name) so you know which device it belongs to.
- Never share your private key file (the one without .pub extension) with anyone.
- If you get a new computer, generate a new SSH key on it and add it to GitHub — do not copy keys between machines.
- Remove old SSH keys from GitHub Settings when you no longer use a device.
- Use ed25519 key type (not RSA) — it is more secure and generates shorter keys.
- If you use multiple tools like Cursor and Replit alongside GitHub Desktop, SSH keys ensure seamless authentication across all of them.
Still stuck?
Copy one of these prompts to get a personalized, step-by-step explanation.
Explain SSH keys to me like I am a non-technical founder. When do I need one for GitHub, and walk me through setting it up on a Mac without any prior terminal experience.
Frequently asked questions
Do I need an SSH key if I only use GitHub Desktop?
No. GitHub Desktop uses its own token-based authentication system. SSH keys are only needed if you use other tools that connect to GitHub via terminal or command line.
Can I use the same SSH key on two different computers?
Technically yes, but it is not recommended. Generate a unique key on each computer and add both to your GitHub account. This way, if one computer is lost or compromised, you can revoke just that key.
What happens if I delete an SSH key from GitHub?
Any computer using that key will lose SSH access to your repositories. You will need to either generate a new key and add it, or switch to HTTPS authentication.
Is SSH more secure than HTTPS for GitHub?
Both are secure. SSH uses cryptographic key pairs while HTTPS uses personal access tokens. SSH is more convenient because you do not need to enter credentials, but both encrypt your connection.
Why does GitHub say 'does not provide shell access' when I test SSH?
This is the expected success message. GitHub does not allow terminal/shell access to its servers — only Git operations. The message confirms your SSH key is working correctly.
Can RapidDev help me set up SSH keys for my team?
Yes. RapidDev can configure SSH authentication, GitHub organization access, and development environment setup for your team across tools like Cursor, VS Code, and Replit.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation