Use SSH keys with GitLab

{{< details >}}

• Tier: Free, Premium, Ultimate
• Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

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.

[!note] For information on advanced SSH key configuration, see advanced SSH key configuration.

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.

[!note] To view the version of SSH installed on your system, run ssh -V.

Supported SSH key types

{{< history >}}

• Maximum RSA key length changed in GitLab 16.3.

{{< /history >}}

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

Algorithm	Notes
ED25519 (preferred)	More secure and performant than RSA keys. Introduced in OpenSSH 6.5 (2014) and available on most operating systems. Might not be fully supported by all FIPS systems. For more information, see issue 367429.
ED25519_SK	Requires OpenSSH 8.2 or later on both your local client and the GitLab server.
ECDSA_SK	Requires OpenSSH 8.2 or later on both your local client and the GitLab server.
RSA	Less secure than ED25519. If used, GitLab recommends a key size of at least 4096 bits. Maximum key length is 8192 bits due to Go limitations. Default key size depends on your ssh-keygen version.
ECDSA	Security issues related to DSA also apply to ECDSA keys.

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 4096-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:

   shellCopy

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

   For 4096-bit RSA:

   shellCopy

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

3. Press <kbd>Enter</kbd>. Output similar to the following is displayed:

   plaintextCopy

   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:

   plaintextCopy

   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.

6. Add the private SSH key to ssh-agent.

   For example, for ED25519:

   shellCopy

   ssh-add ~/.ssh/id_ed25519
   

Add an SSH key to your GitLab account

{{< history >}}

• Suggested default expiration date for keys introduced in GitLab 15.4.
• Usage types for SSH keys added in GitLab 15.7.

{{< /history >}}

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.

   {{< tabs >}}

   {{< tab title="macOS" >}}

   shellCopy

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

   {{< /tab >}}

   {{< tab title="Linux (requires the xclip package)" >}}

   shellCopy

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

   {{< /tab >}}

   {{< tab title="Git Bash on Windows" >}}

   shellCopy

   cat ~/.ssh/id_ed25519.pub | clip
   

   {{< /tab >}}

   {{< /tabs >}}

2. Sign in to GitLab.

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

4. Select Edit profile.

5. In the left sidebar, select Access > 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, [email protected], or [email protected], 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 [email protected].
   • For GitLab Self-Managed or GitLab Dedicated, use ssh -T [email protected] 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:

   plaintextCopy

   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.

   plaintextCopy

   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. In the left sidebar, select Access > 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

{{< history >}}

• Introduced in GitLab 15.9.

{{< /history >}}

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. In the left sidebar, select Access > 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. In the left sidebar, select Access > SSH keys.
4. Next to the key you want to delete, select Remove ({{< icon name="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.