How To: Set up a GitLab account

Logging in

Navigate to our GitLab instance in a browser. Anyone with a valid Illinois NetID can login to the GitLab website. Enter your NetID credentials and click "Sign In"

Configuring your account

1. Once logged in, you will see a small avatar icon in the top-right corner of the page. Click on it, then click the "Settings" option

2. In "Settings", you can do things like upload an avatar, set multiple email addresses for notifications, adjust the colors of the GitLab interface for your user, and more. In order to actually work with GitLab, you need to create and upload an SSH key to GitLab. Along the left side of the page, click on "SSH Keys"

Creating an SSH key

3. Near the top of the page, it tells you that you need to generate an SSH key before you can add one.  You can click on the "generate it" link to view GitLab's built in documentation for this. This page will explain how to generate an SSH key.

4. Use the terminal to create an SSH key. Open a terminal for the next steps.

• The first thing that you're going to do is actually generate the key. Use a 4096 bit RSA key. In the terminal, type:
  

  ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

• You will want to fill in your Illinois email address where it says  "your_email@example.com". For myself, I would use the command:
  ssh-keygen -t rsa -b 4096 -C "vweathrs@illinois."

• It will ask you where you want to save the key file. The default is "~/.ssh/id_rsa" inside of your home directory.

  If you already have an SSH key at this default location, you will want to give it a different file to save to, otherwise you will overwrite the other key at the default location.

• For this example, I'm going to generate a key called "my-git-ssh-key" in my home's ssh directory of "/Users/vweathrs/.ssh/":
  

  Generating public/private rsa key pair.
Enter file in which to save the key (/Users/vweathrs/.ssh/id_rsa): /Users/vweathrs/.ssh/my-git-ssh-key

• You will also be prompted to assign a password to your SSH key. This is a good security measure to have. If someone were to get your SSH key file, they could not use it without the associated password.
  Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /Users/vweathrs/.ssh/my-git-ssh-key.
Your public key has been saved in /Users/vweathrs/.ssh/my-git-ssh-key.pub.
The key fingerprint is:
SHA256:gWSDSJajtmAUfw7vUS3kusGIqwwlZGLrdJHv6PTR+7U vweathrs@illinois.edu
The key's randomart image is:
+---[RSA 4096]----+
| o+o .+.         |
| o= oooo.        |
|o= * ..+..       |
|Boo X o ..       |
|=+oo O  S        |
|o+o + =          |
|.o o = .   .     |
|+ o . . . . .    |
|.. . . ... E     |
+----[SHA256]-----+

• Now if you look in your "~/.ssh" directory, you can see that there are two files that were created from the SSH key commands:
  $ ls -l ~/.ssh
total 128
-rw-------  1 vweathrs  staff   3326 May 16 17:18 my-git-ssh-key
-rw-r--r--  1 vweathrs  staff    747 May 16 17:18 my-git-ssh-key.pub

• The "my-git-ssh-key" file is what's known as the private key. This is the file that should only exist on your local system or whatever system that you are interacting with git repositories from. The other file called "my-git-ssh-key.pub" is the public key. This is what you will upload to GitLab in order to authenticate yourself to work with git repositories.

Copying the public key into GitLab

5. You need to get the contents of the "my-git-ssh-key.pub" file in order to copy them into GitLab. You can read out the file like so:
$ ls -l ~/.ssh
total 128
-rw-------  1 vweathrs  staff   3326 May 16 17:18 my-git-ssh-key
-rw-r--r--  1 vweathrs  staff    747 May 16 17:18 my-git-ssh-key.pub

• You will see a large output of random characters in the terminal that looks something like this. This is the key.

6. Select and copy the entire key including the "ssh-rsa" at the beginning. Now, back on the GitLab website, navigate to the Gitlab SSH keys page.

Paste the copied key into the large "Key" text box and give the key a title. I'm calling mine the same thing as the key that I generated for convenience. Click the "Add key" button to save it.

• Your key should now show up in the list of keys attached to your account:

Setting your key to be the default when communicating with GitLab

You can create and make use of many SSH keys for various things at the same time. In order to keeps things a little more organized, you can create a "config" file for your SSH keys where you define which keys are used for which things.

1. In the terminal, you're going to create a file called "config" in your "~/.ssh/" directory. This is the same place as the SSH key that you created was placed. In this example, use the "nano" text editor.
   nano ~/.ssh/config
   
   
2. Now, in the text file, enter the following:
   
   This will tell the SSH agent to use the "my-git-ssh" key whenever you are communicating with the gitlab server. You can add other keys to the same file in this manner. It makes it easy to manage multiple SSH keys on the same system.
   Host gitlab.engr.illinois.edu
        IdentityFile ~/.ssh/my-git-ssh-key
   
   
3. Now save the file by pressing:
   "Ctrl + O" then "Enter"
   
   
4. Exit nano by pressing:
   "Ctrl + X"

Graphical Git Clients

If you prefer to work with git graphically rather than on the command line, there are a handful of graphical programs that can be used. See: Git GUI Clients.