Configure SSH Key for Git to Use with GitLab

Here’s a simple run through, let’s say you have a Git Repository (repo) that you want to clone to a development machine, in this case the machine is running Ubuntu Linux 22.0.4.2 LTS. A good way to authenticate with Git is with an SSH key, which is a public private key pair that can be used to authenticate you to the repo to push and pull code to and from it.

First we’ll generate an SSH key, then we’ll add the SSH private key to the ssh-agent, after that we’ll add the public key to GitLab so this is ready for authentication. Once all that is done we’ll then perform a test connection and then clone a repo and push a file up to prove it all works fine.

Generate SSH Key

If you already have generated an SSH key pair then you don’t need to do this step. Otherwise run the below to create your key, and ensure you set a passphrase.

ssh-keygen -t rsa -b 4096 -C your@email.com

You’ll see two files created within ~/.ssh, ensure you only ever share the one ending .pub, which is your public key, the other is your private key which must be kept private!

Add SSH Key to ssh-agent

The ssh-agent is a program that starts when you login and stores your private keys for easy use, you need it running and also for it to have your SSH private key loaded into it.

First start it with:

eval "$(ssh-agent -s)"

Then load in your private key to ssh-agent with something like the below, you only need one or the other of these commands depending on the key type you have created.

ssh-add ~/.ssh/id_rsa
ssh-add ~/.ssh/id_ed25519

You’ll be prompted for your passphrase, you only need to do this once per session, once its added to ssh-agent, you can use it many times within this session without needing to re-enter it, that is what the passphrase is for. You should see:

ubuntu@development:~/.ssh$ ssh-add ~/.ssh/id_ed25519
Identity added: /home/ubuntu/.ssh/id_ed25519 (your@email.com)

Check the key is there with:

ssh-add -l

You should see an entry for the key you just added.

Add Public SSH Key to GitLab

Add the key by using “cat” on your public key file (~/.ssh/id_rsa.pub) and then adding the new SSH key under the “Settings” page of your profile, just copy and paste that bad boy in.

Test Your SSH Access to GitLab

Now let’s test our access to Gitlab, assuming you’ve got the ssh-agent running and your key inserted, you should be able to run the below command without being prompted for your SSH key passphrase.

ubuntu@development:~/gitlab$ ssh -T git@gitlab.com
Welcome to GitLab, @user.name!

Create a Test Project/Repository

Create a test repository on Gitlab, in this example let’s create one called “test”.

Now on your development machine within the home directory (or wherever you want to have your clone of the project kept) run one of the following as per what you are trying to do.

Git Global Setup

The two commands below are a global setup, so you should only need to do this once (on your machine within your profile).

git config --global user.name "User Name"
git config --global user.email "your@email.com"

Create a new repository

Let’s start by cloning the repo “test” that we just created:

git clone git@gitlab.com:user.name/test.git
cd test
git switch --create main
touch README.md
git add README.md
git commit -m "add README"
git push --set-upstream origin main

Now if you refresh the page showing your repository at GitLab and you’ll see the README.md file has been added, this shows that we are all good and ready to go!

Conclusion

So, let’s recap what we’ve done. We’ve created ourselves an SSH public-private SSH keypair, shared the public key with GitLab so we can authenticate with them, created a repo in Gitlab, then cloned the repo to your local development machine.

Additional Information

Here are some other scenarios you might want to explore.

Push an existing folder

cd existing_folder
git init --initial-branch=main
git remote add origin git@gitlab.com:user.name/test.git
git add .
git commit -m "Initial commit"
git push --set-upstream origin main

git push -u origin main

Push an existing Git repository

cd existing_repo
git remote rename origin old-origin
git remote add origin git@gitlab.com:user.name/test.git
git push --set-upstream origin --all
git push --set-upstream origin --tags

Image Attribution