Introduction to Gitlab

Urs Roesch

What is GitLab

GitLab is a complete DevOps platform, delivered as a single application. This makes GitLab unique and creates a streamlined software workflow, unlocking your organization from the constraints of a pieced together toolchain. Learn how GitLab offers unmatched visibility and higher levels of efficiency in a single application across the DevOps lifecycle.

Target audience

The course material presented here is meant for a technically inclined person with a basic proficiency in the Git source management system and an inclination to learn about combining the power of Git with the versatility of GitLab.

Scope & Terminology

GitLab is tightly wedded, as the name suggests, to the git source code management system, its concepts, command and terminology. It helps to be familiar with Git’s interpretations of working directory, staging, repository, branch, tag, commit and revision among others.

For some of the exercises git command are used on the command line to update the content of the GitLab repositories. But for the most time the tutorial evolves GitLab’s web interface.

This document will not cover more advanced topics such as CI/CD scripts and advanced GitOps topics.

Table 1. Terminology Summary
Application	Term	Description
Git	`working directory`	Location of the local copy of the git repository
Git	`staging`	Cached files ready for commit.
Git	`repository`	General term for a git project.
Git	`branch`	An working copy of the repository.
Git	`tag`	A named reference to a revision.
Git	`commit`	Annotated addition to the repository.
Git	`revision`	ditto
GitLab	`merge request`	Request to include changes.

GitLab setup

GitLab setup prerequisites

For the course the following prerequisites have to be met:

Recent version of docker.io

All docker commands are invoked without sudo. It is therefore assumed that the participants user is part of the docker Unix group.

Gitlab docker setup

The examples in this tutorial are based on gitlab-ce (community edition). The docker image and instruction on how to install it can be found on the gitlab docker hub page.

Table 2. Port mapping
Protocol	Local Port	Docker Port
HTTPS	8443	443
HTTP	8480	80
SSH	8422	22

Container start script with prefilled port numbers.

GITLAB_HOSTNAME=gitlab.local
GITLAB_HOME=${HOME}/var/work/gitlab
OMNIBUS=""
OMNIBUS+="external_url \"http://${GITLAB_HOSTNAME}:8480/\";"
OMNIBUS+="gitlab_rails['gitlab_shell_ssh_port'] = 8422;"

function start() {
  [[ -d ${GITLAB_HOME} ]] && mkdir -p ${GITLAB_HOME}
  docker run \
    --detach \
    --hostname ${GITLAB_HOSTNAME} \
    --env GITLAB_OMNIBUS_CONFIG="${OMNIBUS}" \
    --publish 8443:443 \
    --publish 8480:8480 \
    --publish 8422:22 \
    --name gitlab \
    --restart always \
    --volume ${GITLAB_HOME}/config:/etc/gitlab \
    --volume ${GITLAB_HOME}/logs:/var/log/gitlab \
    --volume ${GITLAB_HOME}/data:/var/opt/gitlab \
    gitlab/gitlab-ce:latest
}

start

The initial startup of the container is taking quite some time. Patience until the first connection is required.

Add gitlab.local to the /etc/hosts file.

sudo sed -i \
  -e '/gitlab.local/d' \
  -e '$a\127.0.0.1 gitlab.local' \
  -e '$a\::1 gitlab.local' \
  /etc/hosts

Gitlab account setup

Configure admin account password

After starting the docker container open a browser and navigate to http://gilab.local:8480.

Figure 1. Admin password setup

Create user account

Property	Value
First name	Joe
Last name	Developer
User name	jdev
Email	joe.developer@gitlab.local
Password	topsecret
Role	Software Developer

Property

Value

First name

Joe

Last name

Developer

User name

jdev

joe.developer@gitlab.local

Password

topsecret

Role

Software Developer

Figure 2. User account creation

Figure 3. Define role

Congratulations the initial setup is complete!

Module 1 - User configuration

Goals

Navigate the user setting
Set privacy settings.
Manage ssh public keys.

User profile configuration

For the purpose of the excercises conducted during this tutorial no particular changes in the user profile need to be made but for better recognition the avatar, the privacy setting and the ssh keys are being discussed here.

Navigate to the user' settings

Figure 4. Navigate to the user settings

Change the avatar

Figure 5. Change the avatar

Figure 6. Upload new avatar from image file

For Joe Developer the chosen avatar is a construction worker with hard hat.

Review privacy settings

Figure 7. Privacy settings

Upload ssh public keys

Generate a ssh public key on the command line

$ ssh-keygen -t ed25519 -f ~/.ssh/gitlab (1)
Generating public/private ed25519 key pair.
Enter passphrase (empty for no passphrase): (2)
Enter same passphrase again: (3)
Your identification has been saved in /home/uroesch/.ssh/gitlab
Your public key has been saved in /home/uroesch/.ssh/gitlab.pub
The key fingerprint is:
SHA256:hXWPmuLBU8fnrEYPNBoSDKwXaITn5Jn/Vtvdin6gJI4 uroesch@uroesch-puzzle
The key's randomart image is:
+--[ED25519 256]--+
|   o.o.o. . .    |
|  . = o .+ o o   |
|   * + .o + * o  |
|    * .. + B =   |
|     o  S + o o  |
|      ...+o..+   |
|       +.+ +oo.. |
|      E + o...o .|
|       .   .o... |
+----[SHA256]-----+
$ ls -l ~/.ssh/gitlab*
-rw------- 1 jdev jdev 464 Nov  9 12:09 /home/jdev/.ssh/gitlab (4)
-rw-r--r-- 1 jdev jdev 104 Nov  9 12:09 /home/jdev/.ssh/gitlab.pub (5)

Figure 8. Upload a ssh public key

configuration user settings ssh key confirm

Figure 9. Upload confirmation for ssh public key

Module 2 - Gitlab project

Goals

Create a new GitLab project.
How to navigate a project.
Protect certain branches like master.

Create a new project

In the following steps a new personal public repository is created. The process of creating a new project is assisted and straight forward.

The creation starts with clicking on the boxed plus sign left to the search field.

Figure 10. Create a new project from the top navigation bar

1	Click on tab [Register]
2	Joe for `First name`
3	Developer for `Last name`
4	jdev for `User name`
5	joe.developer@gitlab.local for `Email`
6	topsecret for `Password`
7	Create accout by clicking [Register]

1	The `ssh-keygen` command generates a new key option `-t` specifies the format `ed25519` is the easiest to handle. `-f` specifies the file location and name where to store the generated key.
2	The key can be secured with a passphrase which is highly recommended.
3	Confirm passphrase.
4	The generated private key. Note the file permission. Keep this file safe from other users.
5	The public key is the one to be copied to GitLab. Open the file and copy the content.

1	Navigate to menu item `SSH Keys`.
2	Copy the content of the previously created ssh public key into the text area.
3	Change the title of the key with a name that is uniquely identifiable.
4	Optionally set an expiry date for the key.
5	Click [Add key] to save the key.
6	Previously uploaded key. Modifications are not possible one can only delete the entry.

1	Provide an admin password.
2	Confirm the admin password.
3	Finish process by clicking [Change your password]

1	Select software developer for Role
2	Define role by clicking [Get started!]

1	On the left hand side navigation provides access to the various topics.
2	To change the avatar click on [Choose file].

1	If so desired a user can hide certain information on the profile page from being viewed by other participants. Click on the question mark `?` to get a list of the information to hide. This may be necessary on a publicly accessible instance of GitLab.
2	This setting is only relevant for publicly accessable repositories. If your organization maintains private repositories should changes made to said repositories be shown anonymized.