---
title: "Link GitHub with A SSH Key to MacOS or Linux"
description: "A tutorial that you can follow to create your first GitHub repo and link it via SSH to your laptop."
date: 2026-06-28
categories: ["web-development"]
tags: ["git"]
---

import { Picture } from "astro:assets";
import githubssh1 from "../../assets/images/2210/github_ssh_key.jpeg";
import githubssh2 from "../../assets/images/2210/github_add_ssh_key.jpeg";
import githubssh3 from "../../assets/images/2210/create_repo.jpeg";
import YouTubeEmbed from "../../components/widgets/YouTubeEmbed.astro";

GitHub uses SSH keys to authenticate your machine so you can push, pull, and clone repos without typing your password every time. This guide walks through generating an SSH key on macOS or Linux, adding it to your GitHub account, and pushing your first repository.

## Generate an SSH key

Open a terminal and run:

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

Replace `your_email@example.com` with the email tied to your GitHub account. The `-C` flag is just a label (a comment) — it doesn't affect the key's security.

When prompted, press Enter to accept the default file location (`~/.ssh/id_ed25519`). You'll then be asked for a passphrase. **Set one.** It protects the private key if your machine is ever lost or compromised. The ssh-agent will handle it so you don't have to type it every time.

If you're on a legacy system that doesn't support ed25519 (unlikely in 2025+, but possible), fall back to RSA:

```bash
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
```

**Why ed25519 instead of RSA?** Ed25519 keys are shorter, faster to generate, and cryptographically equivalent to a 4096-bit RSA key. GitHub recommends ed25519 as the default.

## Start the ssh-agent and add your key

### macOS

Start the agent and add your key:

```bash
eval "$(ssh-agent -s)"
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
```

Then configure SSH to automatically load keys into the agent and store the passphrase in your keychain. Create or edit `~/.ssh/config`:

```bash
touch ~/.ssh/config
```

Add these lines:

```
Host github.com
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519
```

If you didn't set a passphrase, omit the `UseKeychain` line. If you get a `Bad configuration option: usekeychain` error, add `IgnoreUnknown UseKeychain` on a separate line under the same `Host` block.

### Linux

Start the agent and add your key:

```bash
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
```

On most modern Linux distros (Ubuntu 22.04+, Fedora, etc.), the ssh-agent starts automatically with your desktop session. If `ssh-add` says "Could not open a connection to your authentication agent," run the `eval` command above first.

## Add the SSH key to GitHub

Copy the public key to your clipboard:

```bash
# macOS
pbcopy < ~/.ssh/id_ed25519.pub

# Linux (with xclip)
xclip -selection clipboard < ~/.ssh/id_ed25519.pub

# Linux (without xclip — just print it, then copy manually)
cat ~/.ssh/id_ed25519.pub
```

Then go to GitHub:

1. Click your profile picture (top right) → **Settings**.
2. In the left sidebar under "Access," click **SSH and GPG keys**.
3. Click **New SSH key**.
4. Give it a title (e.g., "Personal laptop" or "Work MacBook").
5. Paste the public key into the **Key** field.
6. Click **Add SSH key**.

<Picture
  src={githubssh1}
  alt="GitHub SSH key settings page"
/>

<Picture
  src={githubssh2}
  alt="Adding an SSH key to GitHub"
/>

## Test the connection

```bash
ssh -T git@github.com
```

You should see:

```
Hi username! You've successfully authenticated, but GitHub does not provide shell access.
```

If you get a "Permission denied" error, double-check that the key was added correctly and that the ssh-agent has your key loaded (`ssh-add -l` lists loaded keys).

## YouTube walkthrough

<YouTubeEmbed
  url="https://www.youtube.com/embed/aGWACCA2Kcg"
  label="Link GitHub with A SSH Key to MacOS or Linux"
/>

## Create a repo and push from your machine

Now that SSH is set up, you can create a repo on GitHub and push code to it.

### Create the repo on GitHub

On GitHub, click the **+** icon (top right) → **New repository**. Fill in:

- **Repository name** — whatever you want (e.g., `test-repo`).
- **Description** — optional.
- **Private or Public** — your choice.

Click **Create repository**.

<Picture
  src={githubssh3}
  alt="Creating a new GitHub repository"
/>

### Push from the terminal

Make sure git is installed:

```bash
# macOS
brew install git

# Ubuntu/Debian
sudo apt install git -y
```

Then initialize and push:

```bash
# Create and enter the project directory
mkdir test-repo && cd test-repo

# Initialize the git repo
git init

# Create a file
echo "# test-repo" >> README.md

# Stage, commit, and push
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin git@github.com:yourusername/test-repo.git
git push -u origin main
```

Replace `yourusername` with your actual GitHub username.

### Clone an existing repo

```bash
git clone git@github.com:yourusername/some-repo.git
```

After cloning, make your changes, commit, and push as usual.

## Summary of the SSH path

| File | What it is |
|------|------------|
| `~/.ssh/id_ed25519` | Your private key. Never share this. |
| `~/.ssh/id_ed25519.pub` | Your public key. This goes on GitHub. |
| `~/.ssh/config` | SSH client configuration (optional but useful on macOS). |

The private key stays on your machine. The public key can be added to as many GitHub accounts or servers as you need. If you set up a new machine, generate a new key pair and add the public key to GitHub — don't copy the private key between machines.