Setup your SSH-key to join the Forge#

This page will describe how to join the project as a developper, i.e., how to setup your environment to connect to the forge with Git and an SSH key. To learn how to use Git, we recommend the following minimalist tutorial on W3Schools or a more formal one on the official Git webpage.

Useful resources#

Here are useful links for this Tutorial :

A git cheat sheet for remembering useful commands when using git in command lines;
The git website for any troubleshooting;
The gitLab documentation for ssh key creation;

Git is the most common way to code!#

Why using Git?#

There are multiple answers to this question, but the best one is probably to return a question back to you. Did you ever find yourself in one of the following situations?

You changed something in your code (it can be a big refactoring or just a small change) but suddenly nothing works anymore and you really do not know what you did wrong, so you would love so much to go back to the version before the change, but unfortunately you didn’t save any backup.
You work with one (or multiple) colleagues on the same project but years going on, the different versions are totally different programs: you have no idea how to merge them back to a unique version.
You’ve spent the entire day making major changes to your shared document, you save it, and the day after, everything seems back to normal: your colleague made a tiny change the day before, in the morning, and saved his document when he got internet back. Your pretty work is gone because of a freaking internet shut down at your colleague’s side. It isn’t your fault nor your colleague’s, so life even deny you the right to get angry at someone.
You want to share your project with the world, but you wonder how you can send a USB-key to everyone without bankrupt yourself.

If you ever faced one of those situations, you have the answer: with Git, it would never have happened!

What is Git?#

Git is a versioning program. On the official website, it is said that

Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency.

In other words, Git comes between your changes and the save you make. It works like a nice assistant who takes backup of your current work every now and then, adding stickers and classifiers everywhere so that you can always find previous work when you need it. It also plays as a saveguard avoiding version clash.

Conviced? Scroll down!

Install useful apps#

Git#

The first thing you need is to install Git. Git is the program that will manage your different versions of the code, allowing you to commit, clone, push, pull, merge or branch your code.

You can find the installer on the git website. Install it locally (no need for administrator rights). Follow simply the steps. When the installer asks you to add git to your path, say yes. You will then be able to call git from your terminal.

Windows Terminal (Windows) - optional#

If you are using Windows, I recommand to install Windows Terminal that supports powershell by default. You can download it there.

Visual Studio Code#

Visual Studio Code (VS Code) is one of the most appreciated IDE (Integrated Development Editor). Developpers like it because it has many advantages: it colors your code, helps you structure it, integrates a terminal, can be fully configured… but above all, it comes with a monstruous set of extensions, including a built-in Git tool. This tool will help you visualise and handle Git repositories in one clic!

You can download Visual Studio Code here.

To visualize your git history efficiently, you can install the extension named Git Graph.

Do not forget to add VS Code to your path (if not done at installation).

To open a folder in VS Code, there are two ways:

Open a terminal, navigate to the folder, then hit

code .

Open VS Code and clic on File > Open Folder.

Setup your environment#

Configure Git#

To be able to “sign” your changes later on, you need to let Git know who you are. To do so, open a terminal (anywhere) and hit

git config --global user.name "name"

where you will replace name by your name, and then

git config --global user.email "email"

where you will replace email by the email your UCLouvain email address.

Add an SSH-key to your GitLab account#

Finally, you need a key to let Git communicate with the server. Otherwise, anyone could pretend to be you. There are two ways to communicate with the server:

Type your username and password anytime you try to make a change in the code;
Use an SSH key that does it for you. This second option is safer and more comfortable, but a little tricky. Follow the guide!

An SSH key works on the principle of asymetric cyptographic key: you will share a public key with the Forge of UCLouvain (for encoding messages), and decode the messages with your private key, stored on your computer. For more explanation, invoke Wikipedia ;-).

A complete explanation can be found in the gitLab documentation. Here is a summary if you are lazy.

Create the key#

First, check if you operating system is equiped with an SSH agent. If yes, it should give you its name and version while hitting

ssh --V

Check that OpenSSH is installed with an SSH version 6.5 or later. If not, update it. OpenSSH normally comes with Linux, Windows10+ and macOS.

To create the key, open a terminal in your home directory (~/ in Linux and macOs, C:\Users\username\ in Windows, usually) and hit:

ssh-keygen -t ed25519 -C "name_of_my_key"

Replace name_of_my_key with something that reminds you the laptop you are using (ex: “UCLouvain laptop”). This is just a name to help you recognize your keys if you have several ones.

Press enter until a confirmation is displayed.

Add the key to GitLab#

Now that your private and public keys have been created, you need to communicate the public one with the Forge of UCLouvain. To do so:

Copy the public key stored in ~\.ssh\id_ed25519.pub (Linux and macOS) or C:\Users\username\.ssh\id_ed25519.pub. To do so, you can either open the file with an editor and copy its content, or you can hit one of the following commands:
- on macOS:
```
tr -d '\n' < ~/.ssh/id_ed25519.pub | pbcopy
```
- on Linux (requires the xclip package):
```
xclip -sel clip < ~/.ssh/id_ed25519.pub
```
- on Windows (using Windows Terminal with powershell, or Git Bash):
```
cat ~/.ssh/id_ed25519.pub | clip
```
Sign in to the Forge of UCLouvain
On the top right, clic on your avatar and select preferences
On the left bar, select SSH Keys
In the key box, paste your public key (it should start with ssh-ed25519 and finish with your comment)
Click on Add key.

Test your key#

You can now verify that your key is correclty settled and working. Nothing more simple. Just open a terminal and hit:

ssh -T git@forge.uclouvain.be

This command should answer oddly like this:

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)?

This is normal. The Forge is not yet recognized as a trusted host. Just hit yes to authorize this server. It must then greet you like this:

Welcome to GitLab, @username!

Clone the repository#

It is now time to type your very first git command. It is named clone. This one is not very important to remember yet crucial. This is the one that allows you to clone the project repository and later on take part to it.

Create a folder where you would like to place this project. For instance, a folder placed here (Windows) C:\Users\username\projects\.
In the Forge, click on Clone and copy the link under clone with SSH.
Open a terminal and navigate to this folder.
Hit the following command
```
git clone git@forge.uclouvain.be:hydraulics-simulations/watlab.git
```
(note that git@forge... is exactly the copied link, so you do not have to type it by hand!)

Congrat’s: now the project has been created. You rock. Quick quick: go in your folder and observe the structure of the Watlab project!

Possible troubleshooting for UCLouvain users#

For some reason, it appears that the HOME path is settled to z/ in some UCLouvain machines running on Windows. A simple way to change that is to

Open the start bar
Type env in the search field
Click Modify the environment variables for my account
Click on New
Fill in the fileds: - Name: HOME - Value: C:\Users\username where username is your Windows username.
Hit OK.
Hit OK again.

Try again to clone the repository. If it still fails, ask Google or contact someone who knows ;-).