Use SSH keys with GitLab

Use SSH keys to securely authenticate with GitLab without entering your username and password each time you push or pull code.

To use SSH keys with GitLab, you must:

1. Generate an SSH key pair on your local system.
2. Add your SSH key to your GitLab account.
3. Verify your connection to GitLab.

What are SSH keys

SSH uses two keys, a public key and a private key.

• The public key can be distributed.
• The private key should be protected.

It is not possible to reveal confidential data by uploading your public key. When you need to copy or upload your SSH public key, make sure you do not accidentally copy or upload your private key instead.

You can use your private key to sign commits, which makes your use of GitLab and your data even more secure. This signature then can be verified by anyone using your public key.

For details, see Asymmetric cryptography, also known as public-key cryptography.

Prerequisites

To use SSH to communicate with GitLab, you need:

• The OpenSSH client, which comes pre-installed on GNU/Linux, macOS, and Windows 10.
• SSH version 6.5 or later. Earlier versions used an MD5 signature, which is not secure.

Supported SSH key types

To communicate with GitLab, you can use the following SSH key types:

Check for existing SSH key pairs

Before you create a key pair, see if a key pair already exists.

1. Go to your home directory.
2. Go to the .ssh/ subdirectory. If the .ssh/ subdirectory doesn’t exist, you are either not in the home directory, or you haven’t used ssh before. In the latter case, you need to generate an SSH key pair.
3. See if a file with one of the following formats exists:

   Algorithm	Public key	Private key
   ED25519 (preferred)	id_ed25519.pub	id_ed25519
   ED25519_SK	id_ed25519_sk.pub	id_ed25519_sk
   ECDSA_SK	id_ecdsa_sk.pub	id_ecdsa_sk
   RSA (at least 2048-bit key size)	id_rsa.pub	id_rsa
   DSA (deprecated)	id_dsa.pub	id_dsa
   ECDSA	id_ecdsa.pub	id_ecdsa

Generate an SSH key pair

If you do not have an existing SSH key pair, generate a new one:

1. Open a terminal.

2. Run ssh-keygen -t with the key type and an optional comment to help identify the key later. A common option is to use your email address as the comment. The comment is included in the .pub file.

   For example, for ED25519:

   ssh-keygen -t ed25519 -C "<comment>"

   For 2048-bit RSA:

   ssh-keygen -t rsa -b 2048 -C "<comment>"

3. Press Enter. Output similar to the following is displayed:

   Generating public/private ed25519 key pair.
   Enter file in which to save the key (/home/user/.ssh/id_ed25519):

4. Accept the suggested filename and directory, unless you are generating a deploy key or want to save in a specific directory where you store other keys.

   You can also dedicate the SSH key pair to a specific host.

5. Specify a passphrase:

   Enter passphrase (empty for no passphrase):
   Enter same passphrase again:

   A confirmation is displayed, including information about where your files are stored.

A public and private key are generated. Add the public SSH key to your GitLab account and keep the private key secure.

Add an SSH key to your GitLab account

To use SSH with GitLab, copy your public key to your GitLab account. GitLab cannot access your private key.

When you add an SSH key, GitLab checks it against a list of known compromised keys. You cannot add compromised keys because the associated private keys are publicly known and could be used to access accounts. This restriction cannot be configured.

If your key is blocked, generate a new SSH key pair.

To add an SSH key to your GitLab account:

1. Copy the contents of your public key file. You can do this manually or use a script.

   In these examples, replace id_ed25519.pub with your filename. For example, for RSA, use id_rsa.pub.

   macOS

   tr -d '\n' < ~/.ssh/id_ed25519.pub | pbcopy

   Linux (requires the xclip package)

   xclip -sel clip < ~/.ssh/id_ed25519.pub

   Git Bash on Windows

   cat ~/.ssh/id_ed25519.pub | clip

2. Sign in to GitLab.

3. In the upper-right corner, select your avatar.

4. Select Edit profile.

5. On the left sidebar, select SSH Keys.

6. Select Add new key.

7. In the Key box, paste the contents of your public key. If you manually copied the key, make sure you copy the entire key, which starts with ssh-rsa, ssh-dss, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521, ssh-ed25519, sk-ecdsa-sha2-nistp256@openssh.com, or sk-ssh-ed25519@openssh.com, and may end with a comment.

8. In the Title box, type a description, like Work Laptop or Home Workstation.

9. Optional. Select the Usage type of the key. It can be used either for Authentication or Signing or both. Authentication & Signing is the default value.

10. Optional. Update Expiration date to modify the default expiration date. For more information, see SSH key expiration.

11. Select Add key.

Verify your SSH connection

Verify that your SSH key was added correctly, and that you can connect to the GitLab instance:

1. To ensure you connect to the correct server, identify the SSH host key fingerprint:
   • For GitLab.com, see the SSH host keys fingerprints documentation.
   • For GitLab Self-Managed or GitLab Dedicated, see https://gitlab.example.com/help/instance_configuration#ssh-host-keys-fingerprints where gitlab.example.com is the GitLab instance URL.
2. Open a terminal and run this command:
   • For GitLab.com, use ssh -T git@gitlab.com.
   • For GitLab Self-Managed or GitLab Dedicated, use ssh -T git@gitlab.example.com where gitlab.example.com is the GitLab instance URL.

By default, connections use the git username, but GitLab Self-Managed or GitLab Dedicated administrators can change the username.

1. On your first connection, you might need to verify the authenticity of the GitLab host. Follow the on-screen prompts if you see a message like:

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

   You should receive a welcome message.

   Welcome to GitLab, <username>!

   If the message doesn’t appear, you can troubleshoot your SSH connection.

View your SSH keys

To view the SSH keys for your account:

1. In the upper-right corner, select your avatar.
2. Select Edit profile.
3. On the left sidebar, select SSH Keys.

Your existing SSH keys are listed at the bottom of the page. The information includes:

• The title for the key
• Public fingerprint
• Permitted usage types
• Creation date
• Last used date
• Expiry date

Remove an SSH key

You can revoke or delete your SSH key to permanently remove it from your account.

Removing your SSH key has additional implications if you sign your commits with the key. For more information, see Signed commits with removed SSH keys.

Revoke an SSH key

If your SSH key becomes compromised, revoke the key.

Prerequisites:

• The SSH key must have the Signing or Authentication & Signing usage type.

To revoke an SSH key:

1. In the upper-right corner, select your avatar.
2. Select Edit profile.
3. On the left sidebar, select SSH Keys.
4. Next to the SSH key you want to revoke, select Revoke.
5. Select Revoke.

Delete an SSH key

To delete an SSH key:

1. In the upper-right corner, select your avatar.
2. Select Edit profile.
3. On the left sidebar, select SSH Keys.
4. Next to the key you want to delete, select Remove ( ).
5. Select Delete.

SSH key expiration

You can set an expiration date when you add an SSH key to your account. This optional setting helps limit the risk of a security breach.

After your SSH key expires, you can no longer use it to authenticate or sign commits. You must generate a new SSH key and add it to your account.

On GitLab Self-Managed and GitLab Dedicated, administrators can view expiration dates and use them for guidance when deleting keys.

GitLab checks daily for expiring SSH keys and sends notifications:

• At 01:00 AM UTC, seven days before expiration.
• At 02:00 AM UTC on the expiration date.