- Supported SSH key types
- See if you have an existing SSH key pair
- Generate an SSH key pair
- Add an SSH key to your GitLab account
- Two-factor Authentication (2FA)
- Testing that everything is set up correctly
- Working with non-default SSH key pair paths
- Per-repository SSH keys
- Multiple accounts on a single GitLab instance
- Deploy keys
- SSH on the GitLab server
Git is a distributed version control system, which means you can work locally. In addition, you can also share or “push” your changes to other servers. GitLab supports secure communication between Git and its servers using SSH keys.
The SSH protocol provides this security and allows you to authenticate to the GitLab remote server without supplying your username or password each time.
This page can help you configure secure SSH keys which you can use to help secure connections to GitLab repositories.
- If you need information on creating SSH keys, start with our options for SSH keys.
- If you have SSH keys dedicated for your GitLab account, you may be interested in Working with non-default SSH key pair paths.
- If you already have an SSH key pair, you can go to how you can add an SSH key to your GitLab account.
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.
To view the version of SSH installed on your system, run
To communicate with GitLab, you can use the following SSH key types:
- DSA (Deprecated in GitLab 11.0.)
- ECDSA (As noted in Practical Cryptography With Go, the security issues related to DSA also apply to ECDSA.)
Administrators can restrict which keys are permitted and their minimum lengths.
OpenSSH 6.5 introduced ED25519 SSH keys in 2014 and they should be available on most operating systems.
Available documentation suggests that ED25519 is more secure than RSA.
If you use an RSA key, the US National Institute of Science and Technology in
Publication 800-57 Part 3 (PDF)
recommends a key size of at least 2048 bits. The default key size depends on your version of
man page for your installed
ssh-keygen command for details.
Before you create a key pair, see if a key pair already exists.
- On Linux or macOS, go to your home directory.
- Go to the
See if a file with one of the following formats exists:
Algorithm Public key Private key ED25519 (preferred)
RSA (at least 2048-bit key size)
If you do not have an existing SSH key pair, generate a new one.
- Open a terminal.
ssh-keygen -tfollowed by the key type and an optional comment. This comment is included in the
.pubfile that’s created. You may want to use an email address for the comment.
For example, for ED25519:
ssh-keygen -t ed25519 -C "<comment>"
For 2048-bit RSA:
ssh-keygen -t rsa -b 2048 -C "<comment>"
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):
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.
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.
You can update the passphrase for your SSH key.
Open a terminal and type this command:
ssh-keygen -p -f /path/to/ssh_key
At the prompts, type the passphrase and press Enter.
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.
Open a terminal and type this command:
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:
ssh-keygen -o -t rsa -b 4096 -C "<comment>"
Now you can copy the SSH key you created to your GitLab account.
Copy your public SSH key to a location that saves information in text format. The following options saves information for ED25519 keys to the clipboard for the noted operating system:
pbcopy < ~/.ssh/id_ed25519.pub
Linux (requires the
xclip -sel clip < ~/.ssh/id_ed25519.pub
Git Bash on Windows:
cat ~/.ssh/id_ed25519.pub | clip
If you’re using an RSA key, substitute accordingly.
- Navigate to
https://gitlab.comor your local GitLab instance URL and sign in.
- In the top-right corner, select your avatar.
- Select Edit profile.
- In the left sidebar, select SSH Keys.
- Paste the public key that you copied into the Key text box.
- Make sure your key includes a descriptive name in the Title text box, such as Work Laptop or Home Workstation.
- Include an (optional) expiry date for the key under “Expires at” section. (Introduced in GitLab 12.9.)
- Click the Add key button.
SSH keys that have “expired” using this procedure are valid in GitLab workflows. As the GitLab-configured expiration date is not included in the SSH key itself, you can still export public SSH keys as needed.
ssh-rsa) and ending with your email address.
You can set up two-factor authentication (2FA) for Git over SSH.
To test whether your SSH key was added correctly, run the following
command in your terminal (replace
gitlab.com with the domain of
your GitLab instance):
ssh -T email@example.com
The first time you connect to GitLab via SSH, you should verify the
authenticity of the GitLab host that you’re connecting to.
For example, when connecting to GitLab.com, answer
yes to add GitLab.com to
the list of trusted hosts:
The authenticity of host 'gitlab.com (22.214.171.124)' can't be established. ECDSA key fingerprint is SHA256:HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw. Are you sure you want to continue connecting (yes/no)? yes Warning: Permanently added 'gitlab.com' (ECDSA) to the list of known hosts.
Once added to the list of known hosts, you should validate the
authenticity of the GitLab host, once again. Run the above command
again, and you should receive a Welcome to GitLab,
If the welcome message doesn’t appear, you can troubleshoot the problem by running
in verbose mode with the following command:
ssh -Tvvv firstname.lastname@example.org
If you used a non-default file path for your GitLab SSH key pair, configure your SSH client to point to your GitLab private SSH key.
To make these changes, run the following commands:
eval $(ssh-agent -s) ssh-add <path to private SSH key>
Now save these settings to the
~/.ssh/config file. Two examples
for SSH keys dedicated to GitLab are shown here:
# 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
Public SSH keys need to be unique to GitLab, as they bind to your account. Your SSH key is the only identifier you have when pushing code via SSH, that’s why it needs to uniquely map to a single user.
If you want to use different keys depending on the repository you are working on, you can issue the following command while inside your repository:
git config core.sshCommand "ssh -o IdentitiesOnly=yes -i ~/.ssh/private-key-filename-for-this-repository -F /dev/null"
This does not use the SSH Agent and requires at least Git 2.10.
The per-repository method also works for using multiple accounts within a single GitLab instance.
Alternatively, it is possible to directly assign aliases to hosts in
~.ssh/config. SSH and, by extension, Git fails to log in if there is
IdentityFile set outside of a
Host block in
.ssh/config. This is
due to how SSH assembles
IdentityFile entries and is not changed by
IdentityFile entries should point to
the private key of an SSH key pair.
chmod 0400 ~/.ssh/<example_ssh_key>and
chmod 0400 ~/.ssh/<example_sh_key.pub>.
# 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>
Hostaliases are defined as
user_2.gitlab.comfor efficiency and transparency. Advanced configurations are more difficult to maintain; using this type of alias makes it easier to understand when using other tools such as
git remotesub-commands. SSH would understand any string as a
Tanuki2, despite giving very little context as to where they point, would also work.
gitlab repository normally looks like this:
git clone email@example.com:gitlab-org/gitlab.git
To clone it for
gitlab.com with the SSH alias
git clone git@<user_1.gitlab.com>:gitlab-org/gitlab.git
Fix a previously cloned repository using the
git remote command.
The example below assumes the remote repository is aliased as
git remote set-url origin git@<user_1.gitlab.com>:gitlab-org/gitlab.git
Read the documentation on deploy keys.
GitLab integrates with the system-installed SSH daemon, designating a user
git) through which all access requests are handled. Users
connecting to the GitLab server over SSH are identified by their SSH key instead
of their username.
SSH client operations performed on the GitLab server are executed as this user. Although it is possible to modify the SSH configuration for this user to, e.g., provide a private SSH key to authenticate these requests by, this practice is not supported and is strongly discouraged as it presents significant security risks.
The GitLab check process includes a check for this condition, and directs you to this section if your server is configured like this, for example:
$ gitlab-rake gitlab:check Git user has default SSH configuration? ... no Try fixing it: mkdir ~/gitlab-check-backup-1504540051 sudo mv /var/lib/git/.ssh/id_rsa ~/gitlab-check-backup-1504540051 sudo mv /var/lib/git/.ssh/id_rsa.pub ~/gitlab-check-backup-1504540051 For more information see: doc/ssh/README.md in section "SSH on the GitLab server" Please fix the error above and rerun the checks.
Remove the custom configuration as soon as you’re able to. These customizations are explicitly not supported and may stop working at any time.
For current versions of Windows, you can also install the Git and SSH clients with Git for Windows.
Alternative tools include:
If on Git clone you are prompted for a password like
something is wrong with your SSH setup.
- Ensure that you generated your SSH key pair correctly and added the public SSH key to your GitLab profile
- Try manually registering your private SSH key using
ssh-agentas documented earlier in this document
- Try to debug the connection by running
ssh -Tv firstname.lastname@example.org(replacing
example.comwith your GitLab domain)