GitLab - SSH Key Setup

GitLab - Setting Up SSH Keys for Secure Access

Why Use SSH Keys with GitLab?

SSH (Secure Shell) keys provide a secure way to authenticate with GitLab without needing to enter your username and password every time you interact with your remote repositories (e.g., git push, git pull, git clone). Instead of passwords, SSH uses a pair of cryptographic keys: a private key that you keep secret on your computer, and a public key that you upload to GitLab.

Benefits include:

• Enhanced Security: SSH keys are generally more secure than password-based authentication, as they are much harder to guess or crack.
• Convenience: No need to repeatedly type your credentials.
• Automation: Essential for scripts and CI/CD pipelines that need to interact with GitLab repositories.

Generating a New SSH Key Pair

Before generating a new key, it’s good practice to check if you already have one.

Step 1: Check for existing SSH keys. Open your terminal (Git Bash on Windows, Terminal on macOS/Linux) and run:

$ ls -al ~/.ssh

Look for files like id_rsa.pub, id_ecdsa.pub, or id_ed25519.pub. If you see such a .pub file, you likely already have an SSH key pair and can skip to Step 3, unless you want to create a new one.

Step 2: Generate a new SSH key pair. We recommend using the Ed25519 algorithm, which is secure and performant. Replace your_email@example.com with your actual email address associated with your GitLab account.

$ ssh-keygen -t ed25519 -C "your_email@example.com"

When prompted ‘Enter file in which to save the key (~/.ssh/id_ed25519):’, you can press Enter to accept the default location. This will create id_ed25519 (private key) and id_ed25519.pub (public key) in your ~/.ssh directory.

When prompted ‘Enter passphrase (empty for no passphrase):’, you can either enter a secure passphrase or leave it empty. A passphrase adds an extra layer of security: if someone gains access to your computer, they still need the passphrase to use your SSH key. If you enter a passphrase, you’ll be prompted for it each time the key is used (unless you use an SSH agent).

Example of the generation process output:

Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/user/.ssh/id_ed25519): [Press Enter]
Enter passphrase (empty for no passphrase): [Type passphrase or Press Enter]
Enter same passphrase again: [Type passphrase or Press Enter]
Your identification has been saved in /home/user/.ssh/id_ed25519
Your public key has been saved in /home/user/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx your_email@example.com
The key's randomart image is:
+--[ED25519 256]--+
|        .o+=+.   |
|         *.B o . |
|        o.+ O o .|
|       . ..B = . |
|        S   o *  |
|         . . + E |
|          . . o .|
|             .   |
|                 |
+----[SHA256]-----+

Step 3: Add your SSH private key to the SSH agent (Optional but Recommended). This avoids having to re-enter your passphrase every time you use the key.

Start the SSH agent in the background:

$ eval "$(ssh-agent -s)"

Add your SSH private key to the agent (use id_rsa if you generated an RSA key):

$ ssh-add ~/.ssh/id_ed25519

Adding Your SSH Public Key to GitLab

Step 4: Copy your SSH public key to your clipboard. You need the content of the .pub file.

On macOS:

$ pbcopy < ~/.ssh/id_ed25519.pub

On Linux (requires xclip or xsel to be installed):

$ cat ~/.ssh/id_ed25519.pub | xclip -selection clipboard  # Using xclip
# OR
$ cat ~/.ssh/id_ed25519.pub | xsel --clipboard --input   # Using xsel

On Windows (Git Bash):

$ cat ~/.ssh/id_ed25519.pub | clip

If these commands don’t work, you can open the file ~/.ssh/id_ed25519.pub (or id_rsa.pub, etc.) in a text editor and manually copy its entire content. The content typically starts with ssh-ed25519 or ssh-rsa and ends with your email address.

Step 5: Add the public key to your GitLab account.

1. Log in to your GitLab account.
2. In the top-right corner, click your avatar, then select ‘Edit profile’ or ‘Preferences’.
3. In the left sidebar, click ‘SSH Keys’.
4. Paste your copied public key into the ‘Key’ text box.
5. The ‘Title’ field will usually auto-populate with the comment from your SSH key (e.g., your email). You can change this to a more descriptive title if you wish (e.g., ‘My Work Laptop’).
6. Optionally, set an ‘Expires at’ date for the key.
7. Click the ‘Add key’ button.

After adding the key, you should see it listed with its title, fingerprint, and creation date.

Testing Your SSH Connection

Step 6: Test if your SSH connection to GitLab is working. Open your terminal and run:

$ ssh -T git@gitlab.com

Replace gitlab.com with your GitLab instance’s domain if you are using a self-managed GitLab.

The first time you connect, you might see a message like:

The authenticity of host 'gitlab.com (xxx.xxx.xxx.xxx)' can't be established.
ECDSA key fingerprint is SHA256:HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

Type yes and press Enter. You should then see a welcome message, such as:

Welcome to GitLab, @username!

If you see this message, your SSH key is correctly set up. If you encounter issues, common problems include incorrect key permissions or the SSH agent not running or configured properly. Consult GitLab’s documentation for troubleshooting SSH issues.

For further details and troubleshooting, refer to the official GitLab documentation on SSH keys: GitLab SSH Documentation (Note: This is a conceptual link, as per requirements, no live links are added if not text). It is often helpful to search for ‘GitLab SSH key setup’ in your preferred search engine for the most up-to-date official guide.