SSH Key Setup: Generating Keys, Adding to GitHub, and Testing the Connection
The previous lesson introduced SSH cloning as the more convenient option for frequent collaboration, contingent on having a registered SSH key. This lesson walks through the complete, one-time setup process: generating a cryptographic key pair on your machine, registering its public half with GitHub, and confirming the connection actually works before relying on it.
Learning Objectives
- Generate a new SSH key pair using ssh-keygen.
- Understand the distinction between the private key and public key, and why only one is ever shared.
- Add a public key to a GitHub account through account settings.
- Test the SSH connection to GitHub to confirm authentication is working correctly.
Key Terms to Know Before Setting Up SSH Keys for GitHub
- SSH key pair: Two mathematically related cryptographic keys — a private key (kept secret, never shared) and a public key (safe to share) — used together to prove identity without transmitting a password.
- ssh-keygen: The command-line tool used to generate a new SSH key pair.
- Private key: The secret half of an SSH key pair, stored securely on your machine and never shared with anyone or any service.
- Public key: The shareable half of an SSH key pair, registered with a service like GitHub to allow it to verify your identity using the corresponding private key.
- ssh-agent: A background program that holds your decrypted private key in memory, so you aren't prompted for its passphrase on every single use.
How SSH Key Authentication With GitHub Actually Works
SSH authentication relies on **asymmetric cryptography**: a mathematically linked pair of keys, where anything encrypted with one key can only be decrypted with the other. You keep the **private key** completely secret on your own machine — it should never be shared, emailed, or committed to any repository. You share the **public key** freely; in this case, by registering it with your GitHub account. When you connect, GitHub can verify that you possess the matching private key without that key ever being transmitted anywhere, providing strong, password-free authentication.
**Step 1: Generate a new key pair**, if you don't already have one, using `ssh-keygen`:
```
ssh-keygen -t ed25519 -C "your_email@example.com"
```
The `-t ed25519` flag specifies a modern, secure key type (GitHub also supports the older RSA type if needed for compatibility with very old systems). The `-C` flag attaches a comment (typically your email) to help identify the key later. You'll be prompted for a file location (the default is almost always fine) and an optional passphrase — adding a passphrase provides an extra layer of security (protecting the key itself if your machine is compromised), at the cost of needing to enter it when the key is first used each session (though `ssh-agent`, described below, minimizes this friction).
This creates two files: a private key (commonly `id_ed25519`) and a public key (`id_ed25519.pub`) inside your `~/.ssh` directory.
**Step 2: Copy the public key's contents.** You need the exact text content of the `.pub` file (not the private key file) to register with GitHub:
```
cat ~/.ssh/id_ed25519.pub
```
**Step 3: Add the public key to GitHub.** In GitHub's account settings, under 'SSH and GPG keys', paste the copied public key content and save it, giving it a descriptive title (like 'Work Laptop' or 'Personal MacBook') so you can identify and revoke it individually later if needed.
**Step 4: Test the connection.** Rather than guessing whether everything is configured correctly, GitHub provides a dedicated way to test an SSH connection directly:
```
ssh -T git@github.com
```
A successful first-time connection will show a warning about the host's authenticity (since you haven't connected to this specific server before) — type `yes` to continue — followed by a confirmation message like:
```
Hi username! You've successfully authenticated, but GitHub does not provide shell access.
```
This message, despite mentioning no shell access (which is expected and correct — you're not trying to log into a shell, just verifying authentication), confirms your SSH key setup is working correctly and ready for cloning, pushing, and pulling.
Finally, if you set a passphrase on your key, `ssh-agent` (often started automatically by your OS or IDE) can hold your decrypted key in memory for the duration of your session, so you're not prompted for the passphrase on every single Git operation — only once per session (or per reboot, depending on configuration).
SSH Key Setup: Visual Walkthrough
Draw a four-step vertical flow. Step 1: 'ssh-keygen -t ed25519 -C "email"' → produces two files: a locked padlock icon labeled 'id_ed25519 (PRIVATE — never share)' and an open padlock icon labeled 'id_ed25519.pub (PUBLIC — safe to share)'. Step 2: arrow from the public key icon to a GitHub settings page mockup labeled 'Settings > SSH and GPG keys > New SSH key — paste public key here'. Step 3: 'ssh -T git@github.com' → a terminal box showing 'Hi username! You've successfully authenticated...'. Step 4: a checkmark labeled 'SSH authentication ready — clone/push/pull without repeated passwords.'
SSH Key Setup Steps: Quick Reference Table
| Step | Command / Action | Purpose |
|---|---|---|
| 1. Generate key pair | ssh-keygen -t ed25519 -C "email" | Creates a private key (secret) and public key (shareable) in ~/.ssh |
| 2. View the public key | cat ~/.ssh/id_ed25519.pub | Copies the exact text needed for registration with GitHub |
| 3. Register with GitHub | GitHub Settings > SSH and GPG keys > New SSH key | Registers your public key so GitHub can verify your identity |
| 4. Test the connection | ssh -T git@github.com | Confirms authentication is working before relying on it |
Generating and Registering an SSH Key: Command Syntax
# Step 1: Generate a new SSH key pair
ssh-keygen -t ed25519 -C "asha.mehta@example.com"
# Enter file in which to save the key (~/.ssh/id_ed25519): [press Enter for default]
# Enter passphrase (optional but recommended): ********
# Step 2: View and copy the public key
cat ~/.ssh/id_ed25519.pub
# ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... asha.mehta@example.com
# (copy this entire line, then paste it into GitHub's SSH key settings)
# Step 3: Test the connection to GitHub
ssh -T git@github.com
# The authenticity of host 'github.com' can't be established. Continue? (yes/no): yes
# Hi asha-mehta! You've successfully authenticated, but GitHub does not provide shell access.
# Step 4: Now cloning/pushing via SSH works without a password prompt
git clone git@github.com:asha-mehta/my-project.gitBreaking Down the SSH Key Setup Example
`ssh-keygen` generates the key pair, prompting for a file location and optional passphrase. `cat ~/.ssh/id_ed25519.pub` displays the exact public key text needed for GitHub — critically, never the private key file, which stays local and secret. The `ssh -T git@github.com` test is the crucial verification step: the success message confirms GitHub correctly recognizes the registered public key and can authenticate the corresponding private key holder, even though the message pointedly notes no shell access is granted (which is expected, since this is purely an authentication test, not an attempt to log into a server). Once confirmed, SSH-based clone, push, and pull operations work without further password prompts.
How SSH Key Authentication Is Used on Real Engineering Teams
- Nearly every professional software engineering onboarding process includes SSH key setup as one of the first required steps, often documented explicitly in a company's engineering onboarding checklist.
- Security-conscious organizations sometimes require SSH keys to have a mandatory passphrase and may enforce periodic key rotation as part of broader security compliance policies.
- Developers commonly maintain a distinct SSH key per machine (e.g., 'Work Laptop', 'Personal Desktop'), registering each separately on GitHub, so that access from any single compromised machine can be individually revoked without affecting others.
- CI/CD systems and automated deployment pipelines frequently use dedicated, narrowly-scoped 'deploy keys' — a special, repository-specific form of SSH key — rather than a personal developer's own key, as a security best practice.
SSH Key Setup Interview Questions and Answers
Q1. What is the difference between the private and public key in an SSH key pair, and how are they used with GitHub?
The private key is kept secret on your own machine and must never be shared. The public key is safe to share and is registered with your GitHub account. When authenticating, GitHub uses the registered public key to verify that you possess the corresponding private key, without the private key itself ever being transmitted.
Q2. What command would you use to generate a new SSH key pair, and what does each part of it do?
ssh-keygen -t ed25519 -C "email" generates a new key pair. -t ed25519 specifies a modern, secure key type, and -C attaches a comment (typically an email address) to help identify the key later. This produces both a private key file and a corresponding .pub public key file.
Q3. How would you verify that your SSH key setup with GitHub is working correctly?
Run ssh -T git@github.com. A successful setup returns a message like 'Hi username! You've successfully authenticated, but GitHub does not provide shell access.' — confirming your registered public key correctly matches your local private key, even though no interactive shell access is being granted (which is expected).
SSH Key Setup Quiz: Test Your Understanding
1. Which key in an SSH key pair should be registered with GitHub?
- The private key
- The public key
- Both keys together
- Neither — GitHub generates its own keys
Answer: B. The public key
Explanation: Only the public key, which is safe to share, should ever be registered with a service like GitHub. The private key must always remain secret on your own machine.
2. What does the command ssh -T git@github.com do?
- Generates a new SSH key pair
- Uploads your public key automatically to GitHub
- Tests whether your SSH connection and authentication with GitHub are working correctly
- Deletes an existing SSH key
Answer: C. Tests whether your SSH connection and authentication with GitHub are working correctly
Explanation: This command specifically tests the SSH connection, confirming whether your registered public key correctly matches your local private key, without attempting any actual Git operation.
3. What file typically contains your PUBLIC SSH key, ready to be copied to GitHub?
- id_ed25519 (no extension)
- id_ed25519.pub
- known_hosts
- config
Answer: B. id_ed25519.pub
Explanation: The .pub file extension conventionally denotes the public key half of the pair, safe to share and register with services like GitHub, unlike the private key file without that extension.
Common SSH Key Setup Mistakes Beginners Make
- Accidentally sharing or uploading the private key file instead of the public (.pub) key file, which compromises the security of the entire key pair.
- Skipping the connection test (ssh -T git@github.com) and only discovering an SSH misconfiguration later, at an inconvenient moment when trying to push.
- Forgetting which specific SSH key was registered on which machine, causing confusion when troubleshooting authentication issues across multiple devices.
- Choosing not to set a passphrase at all for convenience, without weighing the reduced security if the private key file itself were ever compromised.
SSH Key Setup: Exam-Ready Quick Notes
- SSH key pair: private key (secret, local only) + public key (shareable, registered with GitHub).
- ssh-keygen -t ed25519 -C "email": generates a new key pair.
- Only the .pub file's content should ever be shared or registered with GitHub.
- ssh -T git@github.com: tests the connection; success message confirms authentication is working.
SSH Key Setup: Key Takeaways
- SSH key setup is a one-time process that, once complete, enables frictionless, password-free authentication for all future SSH-based Git operations.
- The private key must always remain secret; only the public key is ever shared or registered with a service like GitHub.
- Testing the connection with ssh -T git@github.com before relying on it is a simple, valuable habit to catch configuration issues early.
Frequently Asked Questions About SSH Key Setup
Q1. How do I generate an SSH key for GitHub?
Run ssh-keygen -t ed25519 -C "your_email@example.com" in your terminal, accepting the default file location (or choosing your own), and optionally setting a passphrase for additional security. This creates both a private key and a public (.pub) key file.
Q2. Which key do I add to GitHub — the private or public one?
Only the public key (the file ending in .pub) should ever be added to GitHub or shared with anyone. The private key must always remain secret on your own machine.
Q3. How do I add my SSH key to my GitHub account?
Copy the full contents of your public key file (e.g., using cat ~/.ssh/id_ed25519.pub), then go to GitHub's account Settings, navigate to 'SSH and GPG keys', and paste it in as a new SSH key.
Q4. How can I check if my SSH connection to GitHub is set up correctly?
Run ssh -T git@github.com in your terminal. If everything is configured correctly, you'll see a message like 'Hi username! You've successfully authenticated, but GitHub does not provide shell access,' confirming your key is working.
Q5. Why does the successful SSH test message mention 'no shell access'?
Because the test is purely checking authentication, not attempting to log into an actual server shell — GitHub doesn't provide interactive shell access via SSH, so this message is expected and simply confirms your key was recognized correctly.
Summary
Setting up SSH authentication with GitHub involves generating a cryptographic key pair with `ssh-keygen -t ed25519 -C "email"`, which creates a secret private key (kept only on your local machine) and a shareable public key (found in the `.pub` file). The public key's exact content is then registered with your GitHub account under SSH and GPG key settings, allowing GitHub to verify your identity against the corresponding private key without ever transmitting it. Testing the setup with `ssh -T git@github.com` confirms everything is correctly configured, returning a success message despite noting no shell access is granted (which is expected, since this is purely an authentication check). Once verified, SSH-based cloning, pushing, and pulling work without repeated password or token prompts.