DEV Community

codingKrills
codingKrills

Posted on

How to set up SSH on a new MacBook (M1) and connect to GitHub

TL;DR (what you'll do)

  1. Check for existing SSH keys.
  2. Create a new ed25519 SSH key (recommended).
  3. Add the key to the ssh-agent and macOS Keychain.
  4. Add the public key to your GitHub account.
  5. Configure ~/.ssh/config so your key loads automatically.
  6. Test the connection and switch existing repos to SSH.

Why SSH?

SSH lets your Mac authenticate with GitHub without typing your username/password (or a PAT) for every git push. It's secure, fast, and the standard for developers.

1) Check for existing keys

Open Terminal and run:

ls -al ~/.ssh
Enter fullscreen mode Exit fullscreen mode

If the folder doesn't exist or you don't see id_ed25519/id_rsa, you're clear to create a new key. If you see keys you still want to keep, note their names.

2) Generate a new key (use ed25519 if possible)

ed25519 is modern and compact. Replace the email with your GitHub email:

ssh-keygen -t ed25519 -C "your_email@example.com"
Enter fullscreen mode Exit fullscreen mode

When prompted for a file to save the key, press Enter to accept the default (~/.ssh/id_ed25519) unless you want multiple keys. Add a passphrase for an extra layer of security (recommended), or press Enter to leave it empty.

If ed25519 isn’t supported on your system, use RSA:

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
Enter fullscreen mode Exit fullscreen mode

3) Start the ssh-agent and add your key

Start the agent in your shell session:

eval "$(ssh-agent -s)"
Enter fullscreen mode Exit fullscreen mode

Then add your new private key to the agent and (on macOS) save the passphrase in the Keychain so you won't need to enter it repeatedly.

# On macOS Monterey (12.0) and later (Apple's ssh-add):
ssh-add --apple-use-keychain ~/.ssh/id_ed25519

# On older macOS versions (pre-Monterey) you can use:
ssh-add -K ~/.ssh/id_ed25519

# Fallback (simple add, no keychain behaviour):
ssh-add ~/.ssh/id_ed25519
Enter fullscreen mode Exit fullscreen mode

If ssh-add --apple-use-keychain fails (e.g. ssh-add: illegal option -- apple-use-keychain), you're probably using a non-Apple ssh-add (Homebrew’s OpenSSH). Check which binary is being used with which ssh-add and use /usr/bin/ssh-add --apple-use-keychain ~/.ssh/id_ed25519 or remove/adjust the Homebrew version.

4) Configure ~/.ssh/config so macOS automatically uses your key

Create or edit ~/.ssh/config and add these lines (this makes the ssh-agent use your key and use Keychain on macOS):

Host github.com
  HostName github.com
  User git
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519
Enter fullscreen mode Exit fullscreen mode

This is especially helpful if you have multiple keys or want passphrases remembered.

5) Copy the public key and add it to GitHub

Copy the public key to clipboard (macOS):

pbcopy < ~/.ssh/id_ed25519.pub
Enter fullscreen mode Exit fullscreen mode

Or display it for manual copy:

cat ~/.ssh/id_ed25519.pub
Enter fullscreen mode Exit fullscreen mode

Then in GitHub: Settings → SSH and GPG keys → New SSH key. Give it a descriptive title (e.g. MacBook-M1) and paste the key.

6) Test the connection

Run:

ssh -T git@github.com
Enter fullscreen mode Exit fullscreen mode

On success you'll see something like:

Hi <your-username>! You've successfully authenticated, but GitHub does not provide shell access.
Enter fullscreen mode Exit fullscreen mode

If you see Permission denied (publickey), continue to the troubleshooting section below.

7) Switch an existing repo to SSH (if needed)

Inside your repo:

git remote -v
# to check current remote, if it shows https, switch it to ssh:
git remote set-url origin git@github.com:USERNAME/REPO.git
Enter fullscreen mode Exit fullscreen mode

Or clone using SSH:

git clone git@github.com:USERNAME/REPO.git
Enter fullscreen mode Exit fullscreen mode

Troubleshooting

ssh-add: illegal option -- apple-use-keychain

  • Cause: ssh-add installed from Homebrew (or another source) doesn't include Apple's --apple-use-keychain flag.
  • Fix: Run which ssh-add to see which binary is being used. Apple's ssh-add lives at /usr/bin/ssh-add. Call it directly or remove/adjust the PATH for the Homebrew ssh. See the ssh-add --apple-use-keychain behaviour in man ssh-add if necessary.

Permission denied (publickey)

  • Common causes:

    • The private key wasn't loaded to the agent. Run ssh-add -l to list loaded keys.
    • Wrong file permissions on ~/.ssh or key files. Fix with: 
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub
Enter fullscreen mode Exit fullscreen mode
  • You added the wrong public key to GitHub (copy/paste error). Re-copy with pbcopy < ~/.ssh/id_ed25519.pub.
  • The remote is still using HTTPS — check with git remote -v.

Verbose debug output
Run a verbose SSH attempt to see what key is being offered:

ssh -vT git@github.com
Enter fullscreen mode Exit fullscreen mode

Multiple GitHub accounts (personal vs work)
If you need separate keys for different accounts, create two keys:

# personal
ssh-keygen -t ed25519 -C "personal@example.com" -f ~/.ssh/id_ed25519_personal

# work
ssh-keygen -t ed25519 -C "work@example.com" -f ~/.ssh/id_ed25519_work
Enter fullscreen mode Exit fullscreen mode

Then add them to your ~/.ssh/config:

# Personal
Host github-personal
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_personal
  AddKeysToAgent yes
  UseKeychain yes

# Work
Host github-work
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_work
  AddKeysToAgent yes
  UseKeychain yes
Enter fullscreen mode Exit fullscreen mode

Use the host alias when cloning or setting remotes, for example:

git clone git@github-personal:yourusername/yourrepo.git
# or set remote
git remote set-url origin git@github-work:yourorg/repo.git
Enter fullscreen mode Exit fullscreen mode

Extra notes for Apple Silicon (M1) users

  • Homebrew installs on M1 use /opt/homebrew by default; this can install a different ssh/ssh-add under /opt/homebrew/bin which may not support Apple-specific flags. If you face issues with --apple-use-keychain, check which ssh-add and use /usr/bin/ssh-add when necessary.
  • zsh is the default shell on modern macOS. Add ssh-add --apple-load-keychain ~/.ssh/id_ed25519 2>/dev/null or the ssh-add --apple-use-keychain command to your ~/.zshrc if you want keys to load automatically after login.
# Setup SSH & GitHub on macOS (M1)

## Steps

1. Check for existing keys:

   ```

bash
   ls -al ~/.ssh
Enter fullscreen mode Exit fullscreen mode
  1. Generate an ED25519 key (replace email):

bash
   ssh-keygen -t ed25519 -C "your_email@example.com"
Enter fullscreen mode Exit fullscreen mode
  1. Start ssh-agent and add key (macOS):

bash
   eval "$(ssh-agent -s)"
   ssh-add --apple-use-keychain ~/.ssh/id_ed25519
Enter fullscreen mode Exit fullscreen mode
  1. Add the following to ~/.ssh/config:

text
   Host github.com
     HostName github.com
     User git
     AddKeysToAgent yes
     UseKeychain yes
     IdentityFile ~/.ssh/id_ed25519
Enter fullscreen mode Exit fullscreen mode
  1. Copy the public key and add it to GitHub Settings → SSH and GPG keys:

bash
   pbcopy < ~/.ssh/id_ed25519.pub
Enter fullscreen mode Exit fullscreen mode
  1. Test connection:

bash
   ssh -T git@github.com
Enter fullscreen mode Exit fullscreen mode
  1. Switch an existing repo to SSH:

bash
   git remote set-url origin git@github.com:USERNAME/REPO.git
Enter fullscreen mode Exit fullscreen mode

Troubleshooting tips

  • ssh-add --apple-use-keychain not found: run which ssh-add and ensure you're using /usr/bin/ssh-add (Apple’s version).
  • Permission denied (publickey): check ssh-add -l, ssh -vT git@github.com, and file permissions.



---

# Final checklist (quick)
- [ ] Generated a key: `~/.ssh/id_ed25519`
- [ ] Added key to ssh-agent & Keychain
- [ ] Pasted public key into GitHub
- [ ] Confirmed `ssh -T git@github.com` succeeds
- [ ] Updated repo remotes to SSH

---
Enter fullscreen mode Exit fullscreen mode

Top comments (0)