Adding an SSH key to GitLab is a straightforward process that secures your repositories and automates authentication. This guide walks you through generating keys, adding them to your profile, and troubleshooting common issues.
Using deploy keys and personal access keys correctly helps teams manage read and write access without repeatedly entering passwords.
Quick Reference for SSH Key Setup
| Key Type | When to Use | Scopes & Access | Where to Add |
|---|---|---|---|
| Personal SSH Key | Local clones, pushes, and merges on your own repos | Depends on individual user permissions | User profile → SSH Keys |
| Deploy Key | CI/CD and automated scripts for a single project | Read-only by default; can be set to write | Project settings → Repository → Deploy Keys |
| Machine User Key | Service accounts and pipelines acting as a user | Scoped to specific projects or groups | Group or project members, then SSH Keys at user level |
| Project Import Key | Bringing repositories from other hosts into GitLab | Temporary high-level access for import only | Project import settings |
Generating a Secure SSH Key Pair
Before you can add SSH key in GitLab, you need a key pair on your local machine. Use ssh-keygen with a strong algorithm and a memorable passphrase.
For most modern systems, ed25519 offers a good balance of speed and security, while rsa with 4096 bits remains a reliable alternative for legacy environments.
Command Examples for Key Generation
Run these commands in your terminal to create keys, choose file paths, and set a passphrase that you can remember without writing down in plaintext.
- Generate ed25519 key: ssh-keygen -t ed25519 -C "your_email@example.com"
- Generate RSA 4096 key: ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
- View public key for copying: cat ~/.ssh/id_ed25519.pub
Adding Your SSH Key to GitLab User Profile
Once the key pair exists, you add SSH key in GitLab under your user profile so the platform can link your public key to your account.
This step enables you to clone, fetch, and push over SSH without needing to enter your username and password each time you interact with GitLab repositories.
Step-by-Step Addition Process
Navigate to your user settings, paste the public key content, give it a recognizable title, and save. GitLab validates the format and shows errors if the key is malformed or already in use.
Using Deploy Keys for Project-Level Access
Deploy keys are project-specific SSH keys that provide controlled access for automation and integration pipelines. They differ from personal keys because they can be read-only or writable per project.
When you add SSH key in GitLab as a deploy key, you associate a single public key with one project, which is ideal for CI/CD jobs and external system integrations.
Configuration and Management
Project maintainers can add deploy keys in the repository settings, choosing whether the key has read-only or write access, and they can remove keys when integrations change or end.
Troubleshooting and Maintenance
Even after you add SSH key in GitLab, issues may arise from file permissions, agent forwarding, or mismatched key formats. Understanding how to diagnose them saves time during critical workflows.
Check your SSH config, ensure the key file is not world-readable, and confirm that the public key exactly matches what you pasted into GitLab to avoid silent authentication failures.
Common Diagnostic Commands
Use ssh -vT git@gitlab.com to see detailed connection logs, verify key permissions with ls -la on your .ssh directory, and confirm key addition in user settings or project deploy keys lists.
Best Practices for Managing SSH Keys in GitLab
Implementing consistent practices reduces access issues and improves security posture across teams and projects.
- Add SSH key in GitLab only from trusted, offline machines
- Use deploy keys with minimal required access for automation
- Rotate personal and deploy keys regularly and after team changes
- Monitor key usage through GitLab audit logs and disable unused keys
- Document key purposes and owners in your internal inventory
FAQ
Reader questions
Why does GitLab reject my SSH key when the format looks correct?
Line breaks, extra spaces, or incorrect email addresses in the public key can cause GitLab to reject it. Ensure no newlines exist outside the key and that the associated email matches your GitLab account.
Can I add the same SSH key to multiple projects and still keep it secure?
Yes, you can add SSH key in GitLab to multiple projects using personal keys or deploy keys, but prefer deploy keys with read-only access for each project and rotate keys periodically to reduce risk.
How do I rotate an SSH key without breaking CI/CD pipelines? Generate a new key pair, add the new public key to GitLab, update CI/CD variables or repository deploy keys, test the pipelines, and then remove the old SSH key from user and project settings only after everything works. What should I do if ssh -vT git@gitlab.com shows permission denied?
Check that the correct private key is loaded, verify that the key is added to your SSH agent with ssh-add, ensure the deploy key or user key is enabled in GitLab, and confirm that your local key file has restrictive permissions like 600.