Generate SSH Key and add to your GitHub or GitLab Account

If you use GitHub or GitLab regularly, setting up SSH authentication is one of the first things you should do. Once configured, you can clone, pull, push, and manage repositories without entering your username and password every time.

This guide walks you through generating a new SSH key, adding it to your GitHub or GitLab account, and verifying that everything works correctly.

Note: Ed25519 is the recommended SSH key type. If your system doesn't support it, you can use a 4096-bit RSA key instead.

Generate an SSH Key (macOS & Linux)

Open Terminal and generate a new SSH key by running:

ssh-keygen -t ed25519 -C "[email protected]"

Replace [email protected] with the email address associated with your GitHub or GitLab account.

If your system doesn't support the Ed25519 algorithm, generate a 4096-bit RSA key instead:

ssh-keygen -t rsa -b 4096 -C "[email protected]"

You'll be prompted to choose where to save the key.

Enter file in which to save the key (/Users/yourname/.ssh/id_ed25519):

Simply press Enter to accept the default location unless you have a reason to store it elsewhere.

Next, you'll be asked for a passphrase:

Enter passphrase (empty for no passphrase):

Adding a passphrase is recommended because it provides an extra layer of security. If you prefer, you can leave it empty by pressing Enter.

After a few moments, your SSH key pair will be created.

The generated files are:

Never share your private key. Only the .pub file should be added to your Git hosting provider.

Add the Key to the SSH Agent (Optional)

On normal setup, this process should happen automatically.

Start the SSH agent:

eval "$(ssh-agent -s)"

Then add your key.

On Linux:

ssh-add ~/.ssh/id_ed25519

On modern macOS:

ssh-add --apple-use-keychain ~/.ssh/id_ed25519

If the --apple-use-keychain option isn't available, simply use:

ssh-add ~/.ssh/id_ed25519

Copy Your Public Key

macOS

pbcopy < ~/.ssh/id_ed25519.pub

Linux

If xclip is installed:

xclip -sel clip < ~/.ssh/id_ed25519.pub

Otherwise, display the key and copy it manually:

cat ~/.ssh/id_ed25519.pub

Your copied key should begin with something similar to:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA...

Generate an SSH Key (Windows)

You can use either Git Bash, PowerShell, or Windows Terminal.

Generate a new SSH key:

ssh-keygen -t ed25519 -C "[email protected]"

If Ed25519 isn't supported:

ssh-keygen -t rsa -b 4096 -C "[email protected]"

Accept the default save location and optionally choose a passphrase.

Start the SSH Agent

Open PowerShell as Administrator and run:

Get-Service ssh-agent | Set-Service -StartupType Manual
Start-Service ssh-agent

Now open a normal PowerShell window and add your key:

ssh-add $env:USERPROFILE\.ssh\id_ed25519

Copy Your Public Key

cat $env:USERPROFILE\.ssh\id_ed25519.pub | clip

Your public key is now copied to the clipboard and ready to paste into GitHub or GitLab.

Add the SSH Key to GitHub

Once you've copied your public key, adding it to GitHub only takes a minute.

1. Sign in to GitHub.

2. Click your profile picture in the top-right corner.

3. Select Settings.

4. In the left sidebar, click SSH and GPG keys.

5. Click New SSH key.

6. Enter a descriptive title such as Work Laptop or MacBook Pro.

7. Paste your public key into the Key field.

8. Click Add SSH key.

9. Confirm your password or two-factor authentication if prompted.

Verify the Connection

Open a terminal and run:

ssh -T [email protected]

The first time you connect, you'll be asked to verify GitHub's host fingerprint.

Type: yes

If everything is configured correctly, you'll see a message similar to:

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

Your GitHub account is now ready to use SSH for Git operations.

Add the SSH Key to GitLab

If you're using GitLab, the process is very similar.

1. Sign in to GitLab.

2. Click your avatar in the upper-right corner.

3. Select Edit profile.

4. Navigate to Access → SSH Keys.

5. Click Add new key.

6. Paste your copied public key into the Key field.

7. Give it a descriptive title such as Home Desktop or Work Laptop.

8. Optionally choose an expiration date or usage type.

9. Click Add key.

Verify the Connection

Run:

ssh -T [email protected]

If everything is working correctly, you'll see:

Welcome to GitLab, <username>!

Common SSH Commands

Generate a new SSH key:

ssh-keygen -t ed25519 -C "[email protected]"

Add your key to the SSH agent:

ssh-add ~/.ssh/id_ed25519

Display your public key:

cat ~/.ssh/id_ed25519.pub

Test GitHub authentication:

ssh -T [email protected]

Test GitLab authentication:

ssh -T [email protected]

Troubleshooting

Permission denied (publickey)

This usually means your SSH key isn't being used.

Make sure:

• You've uploaded the public key (.pub) to GitHub or GitLab.

• The SSH agent is running.

• Your private key has been added using ssh-add.

Check Loaded Keys

To see which keys are currently loaded:

ssh-add -l

If no identities are listed, add your key again:

ssh-add ~/.ssh/id_ed25519

Already Have an SSH Key?

Before creating another key, check your .ssh directory.

ls ~/.ssh

Common files include:

• id_ed25519

• id_ed25519.pub

• id_rsa

• id_rsa.pub

If you already have a working key, you can simply upload the existing .pub file instead of generating a new one.