Setting Up SSH Key Access for GitHub on macOS

This guide walks you through creating an SSH key, adding it to your GitHub account, and configuring your Mac to use it for secure connections to your repositories.

Phase 1: Generating Your SSH Key Pair

While Xcode sometimes generates keys, it's good practice to know how to create one manually using the recommended ed25519 algorithm.

1. Open Terminal: Go to Applications > Utilities > Terminal.
2. Run the Key Generation Command: Paste the following command, replacing "your_email@example.com" with your actual GitHub email address.

   ssh-keygen -t ed25519 -C "your_email@example.com"

3. Specify Key File Location:
   • You'll be prompted: Enter file in which to save the key (/Users/your_username/.ssh/id_ed25519):
   • Press Enter to accept the default location (~/.ssh/id_ed25519). Using the default name simplifies configuration.
   • (Note: If you choose a custom name, like JackInSquareBox_github_mac from our chat, remember that filename for Phase 3, Step 3).
4. Set a Secure Passphrase:
   • You'll be prompted: Enter passphrase (empty for no passphrase):
   • Type a strong passphrase and press Enter. This adds an extra layer of security; the key is useless without the passphrase. You'll need to confirm it.
   • (Choosing an empty passphrase is less secure but possible).
   • This creates two files in your ~/.ssh directory:
     • id_ed25519 (Your private key - Keep this secret!)
     • id_ed25519.pub (Your public key - This is what you share with GitHub)

Phase 2: Adding Your Public Key to GitHub

GitHub needs to know your public key to grant access.

1. Copy Your Public Key: Use the cat command in Terminal to display your public key. Adjust the filename if you chose a custom one in Phase 1.

   cat ~/.ssh/id_ed25519.pub

   • Select and copy the entire output of this command. It starts with ssh-ed25519 and ends with your email comment.
2. Add Key to GitHub:
   • Log in to GitHub.com.
   • Click your profile picture (top-right) > Settings.
   • In the left sidebar, click SSH and GPG keys.
   • Click New SSH key or Add SSH key.
   • Give it a descriptive Title (e.g., "My New MacBook Pro").
   • Paste the copied public key into the Key field.
   • Click Add SSH key. Confirm with your GitHub password if prompted.
   • (Note: If you see "Key is already in use", it means this exact key was already added, perhaps by Xcode or previously by you).

Phase 3: Configuring Your Mac's SSH Client

This ensures your system (including Terminal, Xcode, Fork, etc.) knows how to find and use your private key.

1. Start the SSH Agent: This background service manages your keys.

   eval "$(ssh-agent -s)"

2. Add Your Private Key to the Agent & Keychain: This loads your key and stores the passphrase securely in macOS Keychain (so you don't type it constantly). Replace id_ed25519 if you used a custom key name.

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

   • Enter your key's passphrase when prompted.
   • Verify it's loaded: ssh-add -l (should show the key's fingerprint).
3. Create/Edit the SSH Config File (Crucial for Reliability/Custom Names): This file explicitly tells SSH which key to use for which host. This step solved the issue where Fork wasn't working initially.
   • Open the file with nano (it will create it if it doesn't exist):

     nano ~/.ssh/config

   • Paste the following configuration block. Important: Change the IdentityFile path if you used a custom key name (like ~/.ssh/JackInSquareBox_github_mac from our chat).

     Host github.com
       HostName github.com
       User git
       AddKeysToAgent yes
       UseKeychain yes
       IdentityFile ~/.ssh/id_ed25519
     

   • Save and Exit: Ctrl+O, Enter, Ctrl+X.
   • Set Secure Permissions:

     chmod 600 ~/.ssh/config

Phase 4: Testing the Connection

1. Test SSH Authentication with GitHub:

   ssh -T git@github.com

   • You might see a message about the authenticity of host 'github.com' if this is your first time connecting. Type yes and press Enter.
   • Success looks like: Hi your-github-username! You've successfully authenticated, but GitHub does not provide shell access.
   • Failure often looks like: git@github.com: Permission denied (publickey). (If you see this, carefully review Phases 2 and 3).

Phase 5: Configuring Your Git Identity

Tell Git who you are for commit authorship. This applies globally to all your projects.

1. Set Your Name:

   git config --global user.name "Your Full Name"

2. Set Your Email: (Use the same email associated with your GitHub account)

   git config --global user.email "your_email@example.com"

3. Verify:

   git config --global --list

Now, your Mac is fully configured to interact securely with GitHub using SSH from Terminal, Xcode, Fork, and other Git tools!