Setting up an SSH Key for GitHub on Linux: Step-by-Step Guide

Introduction / Why This Is Needed

SSH keys are a modern and secure way to authenticate when working with GitHub. Instead of entering your username and password each time, you use a cryptographic key pair. This is not only more convenient but also protects against password interception. After setup, you'll be able to clone, push, and pull repositories without repeated password prompts.

Prerequisites / Preparation

Before you begin, ensure that:

1. You have a GitHub account.
2. The openssh-client package is installed on your Linux computer (usually pre-installed on most distributions). You can verify this with:

   ssh -V
   

   If the command is not found, install it via your package manager (e.g., sudo apt install openssh-client for Ubuntu/Debian).
3. You have terminal access and basic command-line skills.

Step-by-Step Guide

Step 1: Check for Existing SSH Keys

First, check if you already have SSH keys generated in the default ~/.ssh directory. This helps avoid creating duplicates.

ls -la ~/.ssh

Look for files named like id_ed25519 (private key) and id_ed25519.pub (public key), or id_rsa/id_rsa.pub (older format). If these files exist and you want to use them, skip to Step 3. If no keys are present or you want to create new ones, continue.

Step 2: Generate a New SSH Key

Use the ssh-keygen command to generate a new key pair. The Ed25519 algorithm is recommended (modern and secure). If your system doesn't support Ed25519, use rsa with a 4096-bit length.

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

Replace your_email@example.com with the email linked to your GitHub account. You will be prompted to:

1. Save the key in a file — press Enter to use the default path (/home/your_user/.ssh/id_ed25519).
2. Enter a passphrase — recommended for added security. If you don't want a password, press Enter twice (the key will have no passphrase).

After successful execution, two files will appear in the ~/.ssh directory:

• id_ed25519 (private key, never share this)
• id_ed25519.pub (public key, this needs to be added to GitHub)

💡 Tip: If you are using an older distribution without Ed25519 support, replace -t ed25519 with -t rsa -b 4096.

Step 3: Add the Key to ssh-agent

The ssh-agent manages your keys and uses them automatically during connections. First, ensure the agent is running:

eval "$(ssh-agent -s)"

The output should contain the agent's PID (e.g., Agent pid 12345). Then add the private key to the agent:

ssh-add ~/.ssh/id_ed25519

If you set a passphrase during generation, enter it. If the key has no passphrase, it will be added instantly.

⚠️ Important: On some distributions (e.g., Ubuntu), ssh-agent may start automatically at login. If ssh-add outputs Could not open a connection to your authentication agent, first run eval "$(ssh-agent -s)".

Step 4: Copy the Public Key to the Clipboard

Now you need to copy the contents of the public key (the .pub file) to add it to your GitHub settings. The method depends on whether you have a graphical environment:

If you have a GUI and xclip is installed (common in Ubuntu/Debian):

xclip -selection clipboard < ~/.ssh/id_ed25519.pub

If xclip is unavailable or you are in a pure terminal, simply output the key contents and copy manually:

cat ~/.ssh/id_ed25519.pub

The output will be a long string starting with ssh-ed25519 .... Select the entire line (from ssh-ed25519 to the end) and copy it (Ctrl+Shift+C or via your terminal menu).

Step 5: Add the Key to Your GitHub Account

1. Open GitHub in your browser and log into your account.
2. Click your avatar in the top-right corner → Settings.
3. In the left sidebar, select SSH and GPG keys.
4. Click the New SSH key button.
5. In the Title field, enter a descriptive name (e.g., My Laptop - Ubuntu 22.04).
6. In the Key field, paste the copied public key (entirely, without extra spaces or line breaks).
7. Click Add SSH key.

If prompted for your account password, enter it.

Step 6: Test the Connection

Now test if GitHub recognizes your key:

ssh -T git@github.com

Expected output (if everything is correct):

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

If you see this message, your SSH key is configured correctly. If you get an error like Permission denied (publickey), recheck the previous steps (especially adding the key to ssh-agent and to your GitHub settings).

Verification

You can confirm the key works by trying to clone any public repository via its SSH URL (e.g., git clone git@github.com:fixpedia/example.git). If cloning proceeds without a password prompt, the setup was successful.

Also, verify the key is added to the agent:

ssh-add -l

Your key (with the email you specified during generation) should appear in the list.

Troubleshooting

1. Error Permissions 0644 for '~/.ssh/id_ed25519' are too open

The private key must be readable only by the owner. Fix the permissions:

chmod 600 ~/.ssh/id_ed25519

2. Error The authenticity of host 'github.com (140.82.113.3)' can't be established

On first connection to a new host, SSH asks to confirm trust. Simply type yes to add the host key to ~/.ssh/known_hosts.

3. Key stops working after reboot

If you used a passphrase, the agent won't retain keys after reboot. Add the key again or configure ssh-agent to start automatically with your session (e.g., via ~/.bashrc).

4. Cannot copy key to clipboard

Install xclip (for X11 systems) or wl-copy (for Wayland). Alternatively, use the cat method and manual copying as described in Step 4.

5. GitHub rejects the key

Ensure you are copying the public key (the .pub file), not the private one. The content should start with ssh-ed25519 AAAA... or ssh-rsa AAA....