Setting Up SSH Keys for Git on Linux: A Complete Guide

Introduction / Why This Is Needed

Working with Git repositories over HTTPS requires constantly entering a username and password (or token). This is inconvenient and insecure. SSH keys solve both problems:

• Security: A pair of cryptographic keys is used instead of a password. The private key is stored only by you.
• Convenience: After a one-time setup of ssh-agent, no credentials need to be entered for every git push, git pull, or git clone.

This guide is intended for Linux users (Ubuntu, Debian, Fedora, Arch, etc.) and will help you set up seamless and secure work with any Git hosting that supports SSH (GitHub, GitLab, Bitbucket, your own server).

Requirements / Preparation

Before you begin, ensure that:

1. You have Git installed (version 2.30+). Check with: git --version.
2. You have an account on GitHub, GitLab, or another service where you plan to push code.
3. You have access to a Linux terminal (console) with your regular user privileges.
4. The openssh-client package is installed. It is usually present by default. You can check with:

   ssh -V
   

   If the command is not found, install the package:
   • Ubuntu/Debian: sudo apt update && sudo apt install openssh-client
   • Fedora: sudo dnf install openssh-clients
   • Arch: sudo pacman -S openssh

Step-by-Step Instructions

Step 1: Generate a New SSH Key Pair

It is recommended to use the modern and secure ED25519 algorithm. If your system is very old and does not support it, use RSA (minimum 4096 bits).

1. Open the terminal.
2. Run the generation command. You will be prompted to choose a file location (default ~/.ssh/id_ed25519) and set a passphrase.

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

   • -t ed25519 — key type.
   • -C "your_email@example.com" — a comment, usually your email associated with your Git hosting account. This is useful for identification.
3. Configure the passphrase:
   • Strong passphrase (recommended): Protects your private key if someone gains physical access to your disk. You will need to enter it once when starting ssh-agent.
   • Empty passphrase: The key will not be password-protected. Convenient for automation, but less secure. Press Enter twice to leave the field empty.
   
   As a result, two files will appear in the ~/.ssh/ directory:
   • id_ed25519 — private key. NEVER SHARE WITH ANYONE.
   • id_ed25519.pub — public key. You will upload this to the server.

Step 2: Start ssh-agent and Add Your Key

ssh-agent is a helper program that stores your unlocked private key in memory and signs requests on your behalf. This eliminates the need to enter the passphrase for every Git operation.

1. Start the agent (in most modern distributions it starts automatically on login, but it's good to verify):

   eval "$(ssh-agent -s)"
   

   
   The output should look something like: Agent pid 12345.
2. Add your private key to the agent:

   ssh-add ~/.ssh/id_ed25519
   

   
   If you set a passphrase, the system will ask for it now. After successful addition, you will see the message Identity added: /home/username/.ssh/id_ed25519 (your_email@example.com).

Step 3: Copy the Public Key to the Clipboard

You need to transfer the contents of the ~/.ssh/id_ed25519.pub file (entirely, including ssh-ed25519 ... comment) to your account settings on the Git hosting service.

Use the cat command to output and redirect the output to the clipboard (or copy manually):

# For systems with xclip (Ubuntu/Debian: sudo apt install xclip)
cat ~/.ssh/id_ed25519.pub | xclip -selection clipboard
echo "Public key copied to clipboard."

# Alternative: just print to screen and copy with the mouse
cat ~/.ssh/id_ed25519.pub

Step 4: Add the Public Key to Your Service Account

The process is nearly identical for GitHub, GitLab, and other services.

For GitHub:

1. In the top right corner, click your avatar → Settings.
2. In the left menu, select SSH and GPG keys.
3. Click New SSH key.
4. In the Title field, give the key a descriptive name (e.g., "Laptop - Ubuntu 22.04").
5. In the Key field, paste the contents from your clipboard (what you copied in the previous step).
6. Click Add SSH key. You may need to enter your account password to confirm.

For GitLab:

1. Click your avatar → Preferences.
2. In the left menu, select SSH Keys.
3. In the Key field, paste the key. Fill in the Title field as desired.
4. Click Add key.

Step 5: Test the Connection

Before cloning or working with repositories, verify that authentication succeeds.

For GitHub:

ssh -T git@github.com

For GitLab (gitlab.com):

ssh -T git@gitlab.com

For GitLab (self-hosted):

ssh -T git@<your-gitlab-domain>

• On the first connection, you will see a warning about the host's fingerprint. Agree by typing yes.
• A successful result looks something like this:

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

  Or for GitLab:

  Welcome to GitLab, @username!
  

If you see the message Permission denied (publickey), go back to Step 2 and check that the key is added to ssh-agent (ssh-add -l), and that you copied the public key (.pub), not the private one.

Verification

Now try to clone any public repository using its SSH URL (not HTTPS!). For example:

git clone git@github.com:FixPedia/example-repo.git

The process should proceed without any requests for a password or token. If cloning was successful and you can perform git push to your repositories—the setup is complete!

Potential Issues

1. Permission denied (publickey) Error During Test or Clone

• Cause: The server does not see your key or ssh-agent is not offering it.
• Solution:
  1. Check if the key is added to the agent: ssh-add -l. If the list is empty or the key is missing—add it again: ssh-add ~/.ssh/id_ed25519.
  2. Ensure you uploaded the public key (id_ed25519.pub) to your account settings on the server (GitHub/GitLab).
  3. Check that ~/.ssh/config (if it exists) does not have incorrect settings for the host github.com or gitlab.com.

2. Incorrect Permissions on Files in ~/.ssh/

• Cause: SSH is very strict about access permissions. The private key must not be writable by other users.
• Solution: Run these commands:

  chmod 700 ~/.ssh
  chmod 600 ~/.ssh/id_ed25519
  chmod 644 ~/.ssh/id_ed25519.pub
  

3. ssh-agent Problems After Reboot

• Cause: The agent stops when you log out of the system.
• Solution: Configure automatic startup of ssh-agent and key addition at session start. This is often done in the ~/.bashrc or ~/.zshrc file:

  # Autostart agent if not running
  if ! pgrep -u "$USER" ssh-agent > /dev/null; then
      eval "$(ssh-agent -s)"
  fi
  # Add key if not already added
  ssh-add -l > /dev/null || ssh-add ~/.ssh/id_ed25519 2>/dev/null
  

  After adding this, run source ~/.bashrc (or log back in).

4. Server Uses a Non-Standard SSH Port (Not 22)

• Cause: Some corporate or self-hosted Git servers use a port other than 22 (e.g., 2222).
• Solution: Configure SSH for the specific host via the ~/.ssh/config file:

  Host gitlab-company
      HostName gitlab.yourcompany.com
      Port 2222
      User git
      IdentityFile ~/.ssh/id_ed25519_company
  

  Then use the short hostname in the URL: git@gitlab-company:group/project.git.