DEV Community

dpm_bush
dpm_bush

Posted on Originally published at sshflow.com

Set Up GitLab SSH Authentication and Fix the Common Git Gotchas

#productivity #tutorial #devops #beginners

Adding an SSH key to GitLab is only part of the setup. Your public key must be registered to the right account, your SSH client must offer the matching private key, and your repository must use an SSH remote. If any one of those pieces is missing, Git may still ask for credentials or reject access.

1. Find or create a key pair

Before generating a new key, check whether you already have one:

ls ~/.ssh
Enter fullscreen mode Exit fullscreen mode

A common Ed25519 pair is id_ed25519 (private) and id_ed25519.pub (public). The .pub file is the one you can add to GitLab. Never upload or share the private key.

If you need a new pair, generate one with:

ssh-keygen -t ed25519 -C "you@example.com"
Enter fullscreen mode Exit fullscreen mode

Replace the comment with an identifier you recognize. Accept the suggested location or choose a distinct filename if you want to keep this key separate from others. A passphrase helps protect the private key if someone obtains the file.

You can inspect a public key's fingerprint without displaying the private key:

ssh-keygen -lf ~/.ssh/id_ed25519.pub
Enter fullscreen mode Exit fullscreen mode

2. Add the public key to the right GitLab account

Copy the contents of the .pub file. On macOS, for example:

pbcopy < ~/.ssh/id_ed25519.pub
Enter fullscreen mode Exit fullscreen mode

Or print it and copy the complete line:

cat ~/.ssh/id_ed25519.pub
Enter fullscreen mode Exit fullscreen mode

In GitLab, open your user settings and find SSH Keys. Paste the public key, give it a recognizable title such as your computer name, and save it. Choose the authentication usage type for Git-over-SSH access. A signing option is for signing commits, not a substitute for authentication.

If GitLab rejects the key, check that you copied the entire public-key line and that it begins with a key type such as ssh-ed25519. Make sure you did not copy the private key by mistake.

3. Test SSH authentication

For GitLab.com, run:

ssh -T git@gitlab.com
Enter fullscreen mode Exit fullscreen mode

On the first connection, SSH may ask whether to trust the host key. Verify the host fingerprint using trusted GitLab documentation or your organization's instructions before accepting it.

A successful test typically prints a welcome message identifying your GitLab username. GitLab may close the connection afterward; this test checks authentication and does not provide an interactive shell.

For a self-managed GitLab installation, use its hostname instead:

ssh -T git@gitlab.example.com
Enter fullscreen mode Exit fullscreen mode

Replace the example host with your instance's actual hostname. If it uses a nonstandard SSH port, follow the connection instructions from its administrator.

GitLab uses the SSH username git for repository connections. Your local computer username is not how GitLab identifies you; it recognizes the account associated with the key.

4. Make sure the repository uses SSH

A successful SSH test does not change the URL configured for an existing repository. From inside the repository, inspect its remotes:

git remote -v
Enter fullscreen mode Exit fullscreen mode

An SSH remote looks like:

git@gitlab.com:group/project.git
Enter fullscreen mode Exit fullscreen mode

An HTTPS remote starts with https://. If your repository still uses HTTPS, Git will use HTTPS authentication rather than the SSH key.

Copy the SSH URL from the project's Code menu when cloning. To update an existing origin, use the actual URL for your project:

git remote set-url origin git@gitlab.com:group/project.git
git remote -v
Enter fullscreen mode Exit fullscreen mode

Then use Git as usual:

git fetch
git pull
git push
Enter fullscreen mode Exit fullscreen mode

When the connection test and Git disagree

Permission denied (publickey)

The key may not be registered to the account you expect, or your SSH client may be offering a different key. Run a verbose test to see which identities the client tries:

ssh -vT git@gitlab.com
Enter fullscreen mode Exit fullscreen mode

Compare the public key's fingerprint with the key registered in GitLab:

ssh-keygen -lf ~/.ssh/id_ed25519.pub
Enter fullscreen mode Exit fullscreen mode

Also run the test from the same terminal you use for Git. Windows OpenSSH, Git Bash, and WSL may use different SSH clients, key locations, or agents. A key available in one environment may not be available in another. If the key has a passphrase, your SSH client may prompt for it; an available ssh-agent can hold the unlocked key for your session.

SSH works, but Git asks for HTTPS credentials

Check git remote -v. The remote is likely still an HTTPS URL. Switch it to the project's SSH URL if you want Git to use SSH.

Authentication works, but the project is denied

Authentication proves which GitLab account the key belongs to. It does not grant access to every project. Confirm that the account has permission for the repository and that the group and project path in the remote are correct.

Also check the hostname: a key registered on GitLab.com does not automatically authenticate to a separate self-managed instance, or vice versa.

Account keys and deploy keys are different

For normal workstation use, add a key under your GitLab user account. GitLab then checks that user's project permissions.

A deploy key is configured for a project and is intended for an external system or process. Its project scope and read/write permissions are managed separately, so it is not a replacement for an account key when you are working as yourself.

I originally published a more detailed version of this guide on the SSHFlow blog.

I'm also building SSHFlow — an SSH client where every server gets its own workspace for terminals, SFTP, code, and databases.

Top comments (0)