To use GitLab over SSH, create a key pair on your computer, add only the public key to the correct GitLab account, verify the instance’s host key, and test the connection. If SSH still fails, identify whether the problem is the server name, the key Git is offering, or the account and instance accepting it.
Before you start: check your SSH client and instance
You need an OpenSSH client; GitLab’s setup documentation specifies SSH 6.5 or later. Check the installed version with ssh -V. For GitLab.com, the SSH host is gitlab.com. For a self-managed or Dedicated instance, use its actual hostname. The default SSH username is git, though a self-managed administrator can change it.
As an Amazon Associate I earn from qualifying purchases.
Choose a key type that your client and GitLab instance accept. GitLab lists ED25519 as the preferred option, but notes it may not be fully supported on some FIPS systems. If you need RSA for compatibility, GitLab recommends at least 4096 bits and documents a maximum of 8192 bits. Self-managed administrators may impose additional key restrictions. See GitLab’s supported SSH key types.
Recommended Free Tools
Set up a key and connect to GitLab
-
Create a key pair on your computer
Generate an SSH key pair using the instructions for your operating system in GitLab’s SSH key setup guide. Keep the private key on your device. Do not upload it, paste it into GitLab, or share it; the public key is the file you register with your account.
#1 Best Overall
Yubico - Security Key C NFC - Basic Compatibility - Multi-Factor authentication (MFA) Security Key and passkey, Connect via USB-C or NFC, FIDO Certified- POWERFUL SECURITY KEY: The Security Key C NFC is the essential physical passkey for protecting your digital life from phishing attacks. It ensures only you can access your accounts.
- WORKS WITH 1000+ ACCOUNTS: Compatible with Google, Microsoft, and Apple. A single Security Key C NFC secures 100 of your favorite accounts, including email, password managers, and more.
- FAST & CONVENIENT LOGIN: Plug in your Security Key C NFC via USB-C and tap it, or tap it against your phone (NFC) to authenticate. No batteries, no internet connection, and no extra fees required.
- TRUSTED PASSKEY TECHNOLOGY: Uses the latest passkey standards (FIDO2/WebAuthn & FIDO U2F) but does not support One-Time Passwords. For complex needs, check out the YubiKey 5 Series.
- BUILT TO LAST: Made from tough, waterproof, and crush-resistant materials. Manufactured in Sweden and programmed in the USA with the highest security standards.
-
Add the public key to the intended account
In GitLab, open Profile → Access → SSH keys, then add the contents of your public-key file. The key can be configured for authentication, signing, or both; the interface defaults to both. Check the account’s key expiration settings as you add it. The GitLab account-key instructions describe the available fields.
-
Verify the server and test authentication
Before accepting a first-connection host-key prompt, compare the fingerprint shown by SSH with the published fingerprint for the host. For GitLab.com, use GitLab’s SSH host-key fingerprints. For a self-managed instance, verify against that instance’s official information or administrator; do not assume GitLab.com’s fingerprint applies.
Rank #2
Yubico - YubiKey 5C NFC - Multi-Factor authentication (MFA) Security Key and passkey, Connect via USB-C or NFC, FIDO Certified - Protect Your Online Accounts- POWERFUL SECURITY KEY: The YubiKey 5C NFC is the most versatile physical passkey, protecting your digital life from phishing attacks. It ensures only you can access your accounts
- WORKS WITH 1000+ ACCOUNTS: Compatible with popular accounts like Google, Microsoft, and Apple. A single YubiKey 5C NFC secures 100+ of your favorite accounts, including email, password managers, and more
- FAST & CONVENIENT LOGIN: Plug in your YubiKey 5C NFC via USB and tap it, or tap it against your phone (NFC), to authenticate. No batteries, no internet connection, and no extra fees required
- MOST SECURE PASSKEY: Supports FIDO2/WebAuthn, FIDO U2F, Yubico OTP, OATH-TOTP/HOTP, Smart card (PIV), and OpenPGP. That means it’s versatile, working almost anywhere you need it
- PRIMARY & SPARE KEYS: Just like having a spare house key, we recommend buying two YubiKeys - one for daily use and one as a spare. That way you’ll never get locked out of your accounts
Then test using the bare instance hostname:
ssh -T [email protected]For a self-managed or Dedicated instance, substitute its hostname:
Free tools Windows power users keep installed
One-click scans. No signup required.
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.ssh -T [email protected]A successful connection returns a GitLab welcome message. If SSH reports that it cannot verify the host, stop and confirm the fingerprint before proceeding.
Rank #3
Yubico - YubiKey 5 NFC - Multi-Factor authentication (MFA) Security Key and passkey, Connect via USB-A or NFC, FIDO Certified - Protect Your Online Accounts- POWERFUL SECURITY KEY: The YubiKey 5 NFC is the most versatile physical passkey, protecting your digital life from phishing attacks. It ensures only you can access your accounts
- WORKS WITH 1000+ ACCOUNTS: Compatible with popular accounts like Google, Microsoft, and Apple. A single YubiKey 5 NFC secures 100+ of your favorite accounts, including email, password managers, and more
- FAST & CONVENIENT LOGIN: Plug in your YubiKey 5 NFC via USB and tap it, or tap it against your phone (NFC), to authenticate. No batteries, no internet connection, and no extra fees required
- MOST SECURE PASSKEY: Supports FIDO2/WebAuthn, FIDO U2F, Yubico OTP, OATH-TOTP/HOTP, Smart card (PIV), and OpenPGP. That means it’s versatile, working almost anywhere you need it
- PRIMARY & SPARE KEYS: Just like having a spare house key, we recommend buying two YubiKeys - one for daily use and one as a spare. That way you’ll never get locked out of your accounts
-
Use the project’s SSH clone URL
Open the project in GitLab, select Code, and copy its SSH clone URL. Use that URL for cloning or update an existing remote to it. The repository URL belongs in Git’s clone or remote command, not in the hostname position of the SSH connection test.
Diagnose the error by layer
Start with the exact message. A DNS or hostname error points to the destination; a public-key rejection points to key selection, local access, account enrollment, or instance policy. For unclear failures, SSH’s verbose output can show which key it offers and what happens during authentication.
Rank #4
- POWERFUL SECURITY KEY: The Security Key NFC is the essential physical passkey for protecting your digital life from phishing attacks. It ensures only you can access your accounts.
- WORKS WITH 1000+ ACCOUNTS: Compatible with Google, Microsoft, and Apple. A single Security Key NFC secures 100 of your favorite accounts, including email, password managers, and more.
- FAST & CONVENIENT LOGIN: Plug in your Security Key NFC via USB-A and tap it, or tap it against your phone (NFC) to authenticate. No batteries, no internet connection, and no extra fees required.
- TRUSTED PASSKEY TECHNOLOGY: Uses the latest passkey standards (FIDO2/WebAuthn & FIDO U2F) but does not support One-Time Passwords. For complex needs, check out the YubiKey 5 Series.
- BUILT TO LAST: Made from tough, waterproof, and crush-resistant materials. Manufactured in Sweden and programmed in the USA with the highest security standards.
Permission denied (publickey)
Check these causes in order:
- Account enrollment: Confirm the public key is registered to the GitLab account you intend to use, not another account.
- Key support: Confirm the algorithm is supported by the local OpenSSH client and accepted by the GitLab instance. A self-managed administrator may restrict accepted key types.
- Key selection: If you have several keys, SSH may be offering the wrong private key. See GitLab’s SSH troubleshooting guidance for key-selection checks.
- File access and permissions: The private key must be readable by your user. GitLab’s troubleshooting guidance specifies permissions of
600for the private key and700for the.sshdirectory. - Agent state: If your configuration relies on
ssh-agent, check that the key is loaded. A reboot or a new terminal session can leave it unavailable.
To see more detail for a self-managed host, run:
ssh -Tvvv [email protected]Replace the hostname with the instance you actually use. For a Git operation, GitLab also documents collecting SSH details with GIT_SSH_COMMAND="ssh -vvv"; see Git troubleshooting: see what SSH is doing.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPassword prompt while cloning
If a clone over an SSH URL prompts for a password for git@host, SSH authentication is not working as expected. Recheck that you copied the SSH URL, enrolled the public key, selected a compatible private key, and made it available to your agent if needed. On Windows, also check the relevant client and agent setup. GitLab recommends testing the connection with ssh -Tv git@host; replace host with your instance hostname. Its password-prompt troubleshooting page covers further checks.
Best Value
- Security Key : Protect your online accounts against unauthorized access by using FIDO2 and U2F authentication with T110. It's the world's most protective security key that works with windows, Mac OS, Linux as well as Chrome, Firefox, Edge and many other major browsers.
- Certified with the new FIDO2 standard, T110 provides the benefit of fast login and strong protection against phishing, account takeover as well as many other online attactks.
- Works with : Bank of America, Github, Google, Microsoft, DUO, Twitter, Facebook, Dropbox, Apple, ebay, BINANCE, mor and more.
- Fits USB-A port : Insert the T110 security key into the USB-A port of each service and log in conveniently with one touch
- For the driver download and user guide, please visit TrustKey Solutions Home support page.
Could not resolve hostname
Use only the instance hostname in the connection test. For example, gitlab.com:group/project.git is a clone address, not a hostname to pass after git@. Check spelling and the instance URL first. For a self-managed service, also check DNS, VPN access, and whether local name-resolution information is stale. GitLab explains this error in its hostname troubleshooting guide.
Choose the right setup for multiple accounts or repositories
A single account-wide key is simplest when one GitLab account is used from a device. If you use multiple accounts, or need different keys for different repositories, configure SSH to select the intended identity rather than relying on whichever key it tries first.
Multiple accounts: use SSH host aliases
GitLab’s advanced guide shows aliases in the SSH configuration that point to gitlab.com while selecting a corresponding identity file. Use the alias in the Git remote so the right account key is chosen for that connection. Follow GitLab’s advanced SSH configuration guide for the configuration pattern and remote update steps.
One repository: set a repository-specific SSH command
Git supports a per-repository core.sshCommand setting that names a key and uses IdentitiesOnly=yes. GitLab notes this approach does not use ssh-agent and requires Git 2.10 or later. Keep the named private key restricted to its owner. See GitLab’s single-repository key instructions.
When a hardware-backed SSH key makes sense
Most GitLab SSH setups do not require a hardware security key. If you specifically want a FIDO2-backed SSH key, GitLab documents the ED25519_SK and ECDSA_SK key types. These require OpenSSH 8.2 or later on both the local client and GitLab server. Enrollment can fail if the device does not support the requested type or the client’s OpenSSH version is too old; confirm the requirements in GitLab’s supported-key documentation and its FIDO2 troubleshooting notes.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
