CodingBowl

Working with Git and GitHub, pushing and pulling changes effectively and securely is paramount. While HTTPS with Personal Access Tokens (PATs) is a valid option, SSH keys are generally the more secure, convenient, and recommended method for authenticating with GitHub.

Why use SSH with GitHub?

• Enhanced Security: Your private key stays safely on your machine. Only the public key is shared with GitHub.
• Password-less Authentication: Once set up, you won't need to enter your username and PAT for every single push or pull operation.
• Fine-Grained Access: You can revoke individual SSH keys on GitHub without affecting your main account password, making it easy to manage access for different devices.

This guide will walk you through setting up SSH keys specifically for use with GitHub.

Step 1: Check for Existing SSH Keys

Before generating new keys, it's a good idea to see if you already have some. Open your terminal (Git Bash for Windows, Terminal for macOS/Linux) and run:

ls -al ~/.ssh

What to look for:

• If you see files like id_rsa, id_rsa.pub, id_ed25519, id_ed25519.pub, etc., you likely have existing keys. The file ending with .pub is your public key, and the one without the .pub extension is your private key.
• If the command returns "No such file or directory" or a similar error, you don't have an SSH directory or keys yet, and you can proceed to Step 2.

Decision Point:

• If you have keys: You can reuse them. Just proceed to Step 3.
• If you don't have any or prefer to generate a fresh pair: Proceed to Step 2.

Step 2: Generate a New SSH Key Pair

If you need new keys, follow these steps. We'll use the Ed25519 algorithm, which is generally more secure and faster than RSA.

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

Breaking down the command:

• ssh-keygen: The command to generate SSH keys.
• -t ed25519: Specifies the type of key to create (Ed25519 is recommended).
• -C "your_email@example.com": Adds a comment to the public key. This helps GitHub (and you!) identify the key. Use the email associated with your GitHub account.

When prompted during key generation:

1. "Enter a file in which to save the key (/home/youruser/.ssh/id_ed25519):"
   • Press Enter to accept the default location (~/.ssh/id_ed25519). This is the standard and usually best choice.
2. "Enter passphrase (empty for no passphrase):"
   • Highly Recommended: Enter a strong passphrase. This adds an extra layer of security; someone would need both your private key file and this passphrase to use it.
   • If you leave it empty, you won't be prompted for a passphrase later, but your private key will be less secure.
   • You'll be asked to re-enter the passphrase to confirm.

After this, you should see output confirming the key has been generated, along with its fingerprint.

Step 3: Add Your SSH Key to the SSH Agent

The SSH agent is a program that runs in the background and securely holds your private keys, making them available to Git without you having to re-enter your passphrase for every operation.

1. Start the SSH agent (if not already running):

   eval "$(ssh-agent -s)"

   You should see output like Agent pid 12345.

2. Add your private SSH key to the agent:

   ssh-add ~/.ssh/id_ed25519

   • If you named your key something different, replace id_ed25519 with your private key's name.
   • If you set a passphrase in Step 2, you'll be prompted to enter it now.

Note for Windows (Git Bash): Git Bash often starts the SSH agent automatically for you when you launch it. If you have issues, the above commands should still work.

Step 4: Copy Your Public SSH Key

Now you need to get the contents of your public key (the one ending with .pub) so you can add it to your GitHub account. For our example, this is ~/.ssh/id_ed25519.pub.

To copy the key to your clipboard:

• macOS:

  pbcopy < ~/.ssh/id_ed25519.pub

• Linux (if xclip or xsel is installed):

  xclip -selection clipboard < ~/.ssh/id_ed25519.pub
  # OR
  xsel --clipboard < ~/.ssh/id_ed25519.pub

  If you don't have xclip or xsel, you can install them via your distribution's package manager (e.g., sudo apt-get install xclip on Debian/Ubuntu).

• Windows (Git Bash):

  cat ~/.ssh/id_ed25519.pub | clip

• Manual Copy (Universal Fallback):

  If the above commands don't work, you can always display the key's content and copy it manually:

  cat ~/.ssh/id_ed25519.pub

  Then, carefully select and copy the entire output, starting with ssh-ed25519 (or ssh-rsa) and ending with your email address.

Step 5: Add Your Public SSH Key to GitHub

This is the crucial step where you tell GitHub about your new public key.

1. Go to your GitHub Settings: Log in to GitHub, click your profile picture in the top-right corner, and select Settings.
2. Navigate to SSH and GPG keys: In the left sidebar, click SSH and GPG keys.
3. Add a new SSH key: Click the New SSH key or Add SSH key button.
4. Enter key details:
   • Give your key a descriptive Title (e.g., "My Laptop Ed25519 Key" or "Work PC SSH Key").
   • Paste the public key you copied in Step 4 into the "Key" or "Key content" field.
5. Confirm and add: Click Add SSH key. You might be prompted to confirm your GitHub password.

Step 6: Test Your SSH Connection to GitHub

Finally, let's verify that everything is set up correctly and GitHub recognizes your key.

ssh -T git@github.com

What to expect:

• The first time you connect, you might see a warning about the host's authenticity. Type yes and press Enter to confirm and continue.
• Success! You should see a message like: "Hi username! You've successfully authenticated, but GitHub does not provide shell access." (Where username is your GitHub username).

If you see a "permission denied" error, double-check that:

• Your SSH agent is running and your key is added to it (Step 3).
• Your public key was correctly pasted into your GitHub settings (Step 5).
• You're using the correct SSH URL when interacting with repositories.

Using SSH with Your GitHub Repositories

Now that your SSH key is set up and linked to your GitHub account, ensure you're using the SSH URL when cloning or updating remote origins.

Cloning a repository:
When you clone a repository from GitHub, ensure you select the SSH option for the clone URL. It will look something like this:

git clone git@github.com:your-username/your-repository.git

(Instead of https://github.com/your-username/your-repository.git)

Changing an existing repository's remote URL to SSH:
If you previously cloned a repository using HTTPS, you can easily update its remote URL to use SSH:

1. Check your current remote URL:

   git remote -v

2. Set the new SSH remote URL:

   git remote set-url origin git@github.com:your-username/your-repository.git

   (Replace origin if your remote has a different name, and make sure to use your specific GitHub username and repository name).

You've successfully set up SSH keys for your GitHub workflow.