GitLab Troubleshooting: Fixing Permission denied (publickey) Error

This guide provides a step-by-step solution to the common SSH error Permission denied (publickey) when trying to clone, pull, or push to a GitLab repository.

The Problem

You see an error message like this:

Bash

`git@gitlab.com: Permission denied (publickey).

fatal: Could not read from remote repository.

Please make sure you have the correct access rights and the repository exists.`

This means your local machine did not successfully authenticate with GitLab using an SSH key. GitLab doesn't recognize or accept any key you're sending.

???? Quick Fix (5 Minutes)

Follow these steps in order to resolve the issue.

1. Check for an Existing SSH Key

First, see if you already have a key. The most common types are ed25519 (recommended) and rsa.

Bash

ls -l ~/.ssh/id_ed25519 ~/.ssh/id_rsa 2>/dev/null

• If this command lists files, you have a key. Skip to step 3.
• If it says "No such file or directory," you need to create one.

2. Create a New SSH Key (If you don't have one)

Run the following command, replacing the email with the one you use for your GitLab account.

Bash

ssh-keygen -t ed25519 -C "your_email@example.com" -f ~/.ssh/id_ed25519

Press Enter to accept the default file location and again to skip setting a passphrase (or enter one if you want extra security).

3. Start the SSH Agent and Add Your Key

The SSH agent is a background program that handles your private keys.

Bash

Start the agent in the background

eval "$(ssh-agent -s)"

Add your SSH private key to the agent

ssh-add ~/.ssh/id_ed25519`

4. Add Your Public Key to GitLab

You need to tell GitLab about your key. This involves copying the public part of your key (.pub file) and adding it to your GitLab account settings.

Bash

For macOS (copies the key to your clipboard)

pbcopy < ~/.ssh/id_ed25519.pub

For Linux/WSL (prints the key to the terminal, then copy it manually)

cat ~/.ssh/id_ed25519.pub`

Now, go to GitLab:

1. Click your profile picture in the top-right corner.
2. Go to Preferences → SSH Keys.
3. Paste your key into the "Key" field.
4. Give it a descriptive "Title" (e.g., "My Work Laptop").
5. Click Add key.

⚠️ Important: Make sure you are logged into the same GitLab account that has permission to access the wordpressupdates/amazetrading-wp-updates repository.

5. Test the SSH Connection

Verify that GitLab now recognizes your key.

Bash

ssh -T git@gitlab.com

You should see a welcome message with your GitLab username. If you see this, you're all set!

Welcome to GitLab, @YourUsername!

6. Clone the Repository Again

Now, try your git clone command again. It should work.

Bash

git clone git@gitlab.com:wordpressupdates/amazetrading-wp-updates.git

Advanced Troubleshooting: If It Still Fails

If the quick fix didn't work, one of these common issues might be the cause.

<details> <summary><strong>Wrong GitLab Account or Project Permissions</strong></summary>

• Problem: The SSH key is added to GitLab Account A, but the repository requires access from GitLab Account B. Or, your account doesn't have the required permissions (e.g., you're a "Guest").
• Solution:
  1. Confirm you are logged into the correct GitLab account.
  2. Ask a project owner to verify you are a member of the wordpressupdates group or the amazetrading-wp-updates project with at least Developer role.

</details>

<details> <summary><strong>Incorrect File Permissions on Keys</strong></summary>

• Problem: SSH is very strict about security. If your key files or .ssh directory have permissions that are too open, SSH will refuse to use them.

• Solution: Run these commands to set the correct permissions.Bash

  chmod 700 ~/.ssh

  chmod 600 ~/.ssh/id_ed25519

     chmod 644 ~/.ssh/id_ed25519.pub

</details>

<details> <summary><strong>Force a Specific Key via SSH Config (for multiple keys)</strong></summary>

• Problem: If you have multiple SSH keys, your system might be trying to send the wrong one to GitLab.

• Solution: Create or edit the ~/.ssh/config file and explicitly tell SSH which key to use for gitlab.com.

  Open or create the file

  nano ~/.ssh/config

  Add these contents

  Host gitlab.com

  HostName gitlab.com

  User git

  IdentitiesOnly yes

  IdentityFile ~/.ssh/id_ed25519`

  You can get detailed debugging output by running ssh -vT git@gitlab.com to see which key it's offering.

</details>

<details> <summary><strong>Corporate Proxy or Firewall Blocking SSH (Port 22)</strong></summary>

• Problem: Some corporate networks block outgoing traffic on port 22, which is the standard for SSH.

• Solution: GitLab provides an alternative SSH server that runs on port 443 (the standard HTTPS port, which is rarely blocked). Update your ~/.ssh/config file:

  Host gitlab.com HostName altssh.gitlab.com Port 443 User git IdentityFile ~/.ssh/id_ed25519 IdentitiesOnly yes

</details>

<details> <summary><strong>Using HTTPS as a Fallback</strong></summary>

• Problem: If SSH is not an option, you can use HTTPS.

• Solution: Clone the repository using the HTTPS URL. If the repository is private, you will be prompted for a username and password. For the password, you must use a Personal Access Token (PAT) with read_repositoryscope.Bash

  # You can find the HTTPS URL on the project's main page git clone <https://gitlab.com/wordpressupdates/amazetrading-wp-updates.git>

</details>

❓ Common Follow-Up Questions

Q: Do I need to do both ssh-add and add the key to the GitLab UI?

A: Yes, both steps are required. They serve two different purposes:

1. ssh-agent + ssh-add (Local Machine): This loads your private key into your computer's memory. When you run a git command, SSH knows where to find this key to prove your identity to GitLab. Without this, your machine won't send the key.
2. Add Public Key to GitLab (Remote Server): This tells GitLab's server that your public key is authorized to access your account. When your computer sends its private key signature, GitLab checks it against the public keys it has on file. If there's no match, access is denied.

The Flow:

1. You generate a key pair (private and public).
2. You load the private key locally using ssh-agent.
3. You register the public key on the GitLab website.
4. When you connect, your computer and GitLab perform a cryptographic handshake to verify you are who you say you are.

Q: I fixed the SSH key, but now I get fatal: unable to auto-detect email address. What do I do?

A: This is a Git configuration error, not an SSH error. Git needs to know who you are to label your commits correctly. You need to set your name and email.

Option 1: Set Identity Globally (Recommended)

This will apply to all Git repositories on your computer. Use the same email you use for GitLab.

Bash

git config --global user.name "Your Name" git config --global user.email "your_email@example.com"

Option 2: Set Identity for This Repository Only

This is useful if you work on different projects with different identities. Run this inside the repository folder.

Bash

git config user.name "Your Name" git config user.email "your_email@example.com"

You can check your current settings with git config --list.