Advanced SSH key configuration - Gitlabhq

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

Configure advanced SSH key options for specialized workflows.

[!note] For information on basic SSH key usage with your GitLab account, see use SSH keys with GitLab.

Generate an SSH key pair for a FIDO2 hardware security key

To generate ED25519_SK or ECDSA_SK SSH keys, you must use OpenSSH 8.2 or later:

Insert a hardware security key into your computer.
Open a terminal.
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_SK:
shell
```
ssh-keygen -t ed25519-sk -C "<comment>"
```
For ECDSA_SK:
shell
```
ssh-keygen -t ecdsa-sk -C "<comment>"
```
If your security key supports FIDO2 resident keys, you can enable this when creating your SSH key:
shell
```
ssh-keygen -t ed25519-sk -O resident -C "<comment>"
```
-O resident indicates that the key should be stored on the FIDO authenticator itself. Resident key is easier to import to a new computer because it can be loaded directly from the security key by ssh-add -K or ssh-keygen -K.

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

plaintext

Generating public/private ed25519-sk key pair.
You may need to touch your authenticator to authorize key generation.

Touch the button on the hardware security key.

Accept the suggested filename and directory:

plaintext

Enter file in which to save the key (/home/user/.ssh/id_ed25519_sk):

Specify a passphrase:
plaintext
```
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.

Generate an SSH key pair with 1Password

You can use 1Password and the 1Password browser extension to either:

Automatically generate a new SSH key.
Use an existing SSH key in your 1Password vault to authenticate with GitLab.

Sign in to GitLab.
In the upper-right corner, select your avatar.
Select Edit profile.
In the left sidebar, select Access > SSH keys.
Select Add new key.
Select Key, and you should see the 1Password helper appear.
Select the 1Password icon and unlock 1Password.
You can then select Create SSH Key or select an existing SSH key to fill in the public key.
In the Title box, enter a description, like Work Laptop or Home Workstation.
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.
Optional. Update Expiration date to modify the default expiration date.
Select Add key.

For more information about using 1Password with SSH keys, see the 1Password documentation.

Disable SSH keys for enterprise users

Introduced in GitLab 18.8.

Prerequisites:

You must have the Owner role for the group that the enterprise users belong to.

Disabling the SSH Keys of a group's enterprise users:

Stops the enterprise users from adding new SSH Keys.
Disables the existing SSH Keys of the enterprise users.

This also applies to enterprise users who are administrators of the group.

To disable the enterprise users' SSH Keys:

In the top bar, select Search or go to and find your group.
Select Settings > General.
Expand Permissions and group features.
Under Enterprise users, select Disable SSH Keys.
Select Save changes.

Upgrade your RSA key pair to a more secure format

If your version of OpenSSH is between 6.5 and 7.8, you can save your private RSA SSH keys in a more secure OpenSSH format by opening a terminal and running this command:

shell

ssh-keygen -o -f ~/.ssh/id_rsa

Alternatively, you can generate a new RSA key with the more secure encryption format with the following command:

shell

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

Update your SSH key passphrase

You can update the passphrase for your SSH key:

Open a terminal and run this command:
shell
```
ssh-keygen -p -f /path/to/ssh_key
```
At the prompts, enter the passphrase and then press <kbd>Enter</kbd>.

Use different accounts on a single GitLab instance

You can use multiple accounts to connect to a single instance of GitLab. You can do this by using the command in the previous topic. However, even if you set IdentitiesOnly to yes, you cannot sign in if an IdentityFile exists outside of a Host block.

Instead, you can assign aliases to hosts in the ~/.ssh/config file.

For the Host, use an alias like user_1.gitlab.com and user_2.gitlab.com. Advanced configurations are more difficult to maintain, and these strings are easier to understand when you use tools like git remote.
For the IdentityFile, use the path the private key.

conf

# User1 Account Identity
Host <user_1.gitlab.com>
  Hostname gitlab.com
  PreferredAuthentications publickey
  IdentityFile ~/.ssh/<example_ssh_key1>

# User2 Account Identity
Host <user_2.gitlab.com>
  Hostname gitlab.com
  PreferredAuthentications publickey
  IdentityFile ~/.ssh/<example_ssh_key2>

Now, to clone a repository for user_1, use user_1.gitlab.com in the git clone command:

shell

git clone git@<user_1.gitlab.com>:gitlab-org/gitlab.git

To update a previously-cloned repository that is aliased as origin:

shell

git remote set-url origin git@<user_1.gitlab.com>:gitlab-org/gitlab.git

[!note] Private and public keys contain sensitive data. Ensure the permissions on the files make them readable to you but not accessible to others.

Use different keys for different repositories

You can use a different key for each repository.

Open a terminal and run this command:

shell

git config core.sshCommand "ssh -o IdentitiesOnly=yes -i ~/.ssh/private-key-filename-for-this-repository -F /dev/null"

This command does not use the SSH Agent and requires Git 2.10 or later. For more information on ssh command options, see the man pages for both ssh and ssh_config.

Use SSH keys in another directory

If your SSH key pair is not in the default directory, configure your SSH client to point to where you stored the private key.

Open a terminal and run this command:

shell

eval $(ssh-agent -s)
ssh-add <directory to private SSH key>

Save these settings in the ~/.ssh/config file. For example:

conf

# GitLab.com
Host gitlab.com
  PreferredAuthentications publickey
  IdentityFile ~/.ssh/gitlab_com_rsa

# Private GitLab instance
Host gitlab.company.com
  PreferredAuthentications publickey
  IdentityFile ~/.ssh/example_com_rsa

For more information on these settings, see the man ssh_config page in the SSH configuration manual.

Public SSH keys must be unique to GitLab because they bind to your account. Your SSH key is the only identifier you have when you push code with SSH. It must uniquely map to a single user.

Use SSH with EGit on Eclipse

If you use EGit, you can add your SSH key to Eclipse.

Use SSH on Microsoft Windows

On Windows 10, you can either use the Windows Subsystem for Linux (WSL) with WSL 2 which has both git and ssh preinstalled, or install Git for Windows to use SSH through PowerShell.

The SSH key generated in WSL is not directly available for Git for Windows, and vice versa, as both have a different home directory:

WSL: /home/<user>
Git for Windows: C:\Users\<user>

You can either copy over the .ssh/ directory to use the same key, or generate a key in each environment.

If you're running Windows 11 and using OpenSSH for Windows, ensure the HOME environment variable is set correctly. Otherwise, your private SSH key might not be found.

Alternative tools include:

Cygwin
PuTTYgen 0.81 and later (earlier versions are vulnerable to disclosure attacks)

Use two-factor authentication for Git over SSH

You can use two-factor authentication (2FA) for Git over SSH. You should use ED25519_SK or ECDSA_SK SSH keys. For more information, see supported SSH key types.