1. git
  2. gitlab

How to set up your SSH key for GitLab on macOS

One of the most common issues while getting started with Git and GitLab is setting up the private and public keys.


The most common error you may get when trying to close a Git repository over SSH is this one:

[email protected]: Permission denied (publickey,keyboard-interactive). fatal: Could not read from remote repository.

What is SSH?

SSH is a way to authenticate without exposing your username and password.

SSH stands for Secure Shell and is a cryptographic protocol based on the concept of public-private keys.

We are using SSH with Git because it is much easier than typing your username and password all the time, and it is also more secure.

You have probably noticed that GitLab is complaining that you don’t have an SSH key.

You won’t be able to pull or push repositories via SSH until you add an SSH key to your profile

Let’s fix that.

Step 1 — Installing Git

Open any terminal and check if you already have Git installed by typing:

git --version

If you are getting back an error message, you need to install Git. I would anyway recommend installing/updating Git anyway.

Go ahead and open https://git-scm.com/. The latest version I see is 2.31.1.

I would recommend you install Git through Homebrew. If you don’t know what Homebrew is, don’t sweat it. Just to go brew.sh, copy the command you see on the page, open a terminal and run it. This will install Homebrew.

How with Homebrew installed, just run the command brew install git .

Step 2 — Configuring Git

Before we move forward, adapt the following commands with your name and email. They will be part of any changes you make to any Git repository. Do it now, otherwise, your work colleagues will give you a minus point.

git config --global user.name "Your Name"
git config — global user.email "[email protected]"

Step 3 — Cloning a GitLab repository

Log in to your GitLab account and go to the repository you want to clone.

Click on the Clone button and the address under Clone with SSH.

Run the command


If this is the first time you connect to this server, you may also get this warning. Type “yes” and it won’t bother you again.

Getting the next error is normal. We will fix it in a moment.

Could not read from remote repository.

Step 4 — Generating an SSH key

We will be using a tool called ssh-keygen. So open a terminal and run this command:

ssh-keygen -t rsa -b 4096

To make sure the key is very secure, we will also provide two additional parameters:

  • -t to specify the RSA encryption algorithm
  • -b to specify the key size in bits.

First, you will be asked about the location where the keys should be stored. By default, your user folder will contain a folder called .ssh. Leave it as it is and hit the Enter key.

Next, you will be asked to set a password to protect your private key. Without a password, anyone having your private key can impersonate you.

I highly recommend setting a password and storing that password somewhere securely.

If you want to learn how to build pipelines in Gitlab CI, I have created an online course that starts with the basics of Gitlab CI and YAML and helps you understand the fundamentals of CI/CD. Learn more about the course.

Your public/private key pair has been generated.

Let’s recap what you now have:

  • id_rsa — this is your PRIVATE key. Don’t share this with anyone else. This is your secret.
  • id_rsa.pub — this is your PUBLIC key. This contains no secrets. You can share it with others.

Step 5 — Adding your SSH key to GitLab

With your favorite text editor, open your public key. I will use the terminal and the cat command to view the contents of the file.

Copy the entire contents of the file.

In GitLab, go to your profile settings.

From the menu on the left-hand side, select SSH Keys.

Paste your public key in the big text box you see on the screen and finally click Add key. Optionally, you may also give your key a name so that you can easily identify it later.

Step 6 — Cloning a GitLab repository (again)

Now it is time to run the clone command again.

If you have set a passphrase for the SSH key, you will be asked to enter it (more on how to avoid this later).

Step 7 — Using the macOS keychain to store the SSH key passphrase.

Entering your passphrase every time you execute a remote Git command is not practical.

First, we need to let ssh-agent know about our ssh key. We do this by running the following command and enter your passphrase when prompted:


The second step is to store this password in our macOS keychain. To do so, we need to create a configuration file in this location ~/.ssh/config .

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

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

Using vim, I have added the following content to this file:

Host *
UseKeychain yes

Verify that you can connect

Verify that your SSH key was added correctly.

  1. For GitLab.com, to ensure you’re connecting to the correct server, confirm the SSH host keys fingerprints.
  2. Open a terminal and run this command, replacing gitlab.example.com with your GitLab instance URL:
    ssh -T [email protected]
  3. If this is the first time you connect, you should verify the authenticity of the GitLab host. If you see a message like:The authenticity of host 'gitlab.example.com (' 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.example.com' (ECDSA) to the list of known hosts. Type yes and press Enter.
  4. Run the ssh -T [email protected] command again. You should receive a Welcome to GitLab, @username! message.

If the welcome message doesn’t appear, you can troubleshoot by running ssh in verbose mode:

ssh -Tvvv [email protected]

This should be enough to have everything working properly.


I hope this tutorial helped you get started with configuring your Git installation in macOS to work with GitLab. Leave a comment in the section below if you have any questions. I would love to hear from you!

Do you like Ashiqur Rahman's articles? Follow on social!
Comments to: How to set up your SSH key for GitLab on macOS

Your email address will not be published.

Attach images - Only PNG, JPG, JPEG and GIF are supported.


Welcome to rDevs

Brief and amiable onboarding is the first thing a new user sees in the theme.
Join rDevs

start writing