GitLab Tutorial – in­stall­a­tion and first steps in GitLab

GitLab is a popular version control system (VCS) that is mainly used in software de­vel­op­ment. This web-based software was written and published in the ‘Ruby on Rails’ pro­gram­ming language in 2011 by Dmitri Sap­aroschez and is now con­sidered an in­dis­pens­able tool among the developer community.

The main advantage of GitLab is that it makes cross-team, agile software de­vel­op­ment much easier. Several de­velopers can work on a project at the same time and edit different features in parallel, for example. Con­tinu­ous logging of processes ensures that changes to the code are not lost or ac­ci­dent­ally over­writ­ten. In addition, changes that have already been made can be easily undone.

GitLab is based on the widely used Git version control software. As open source software, Git is freely ac­cess­ible and is one of the most popular version control systems. GitLab is one of the leading al­tern­at­ives to GitHub (many users switched to GitLab when GitHub was acquired by Microsoft in 2018).

GitLab is a web-based ap­plic­a­tion with a graphical user interface, but it can also be installed on a private server. Projects are the centrepiece of GitLab. In these projects, the code to be edited is stored in digital archives, which are called re­pos­it­or­ies. All project content and files can be found in these project dir­ect­or­ies, such as JavaS­cript, HTML, CSS or PHP files.

GitLab works like this: First, all team members download their own copy of the central re­pos­it­ory to their computer. Changes to the code are initially made using commits. After editing, the changes are then fed into the main re­pos­it­ory.

Another important feature is branching – branches that diverge from the main code for in­de­pend­ent editing. This lets you add and test new functions without affecting the main line. Built-in con­tinu­ous delivery and con­tinu­ous in­teg­ra­tion mean GitLab is ideal for testing. Useful features like merge requests and forks make it one of the most popular con­tinu­ous in­teg­ra­tion tools.

The main features of GitLab include:

• User-friendly interface
• Branches can remain private or can be shared publicly
• Ability to manage multiple re­pos­it­or­ies
• Code review
• Built-in bug and issue tracking
• Built-in, free con­tinu­ous in­teg­ra­tion/delivery (CI/CD)
• Project wikis
• Easy creation of code snippets for sharing parts of the code

GitLab is based on open, freely ac­cess­ible source code. In 2013, a separate en­ter­prise edition was in­tro­duced for busi­nesses, which is why two delivery models are now available:

• GitLab CE: Community Edition (free)
• GitLab EE: En­ter­prise Edition (paid)

Both versions are based on the MIT open-source license. The En­ter­prise Edition has several ad­di­tion­al features compared to the free Community Edition. GitLab offers three different sub­scrip­tion models depending on the scope of ad­di­tion­al features required.

In addition, the En­ter­prise Edition can be used free of charge, but it only includes the basic functions of the Community Edition. This model is ap­pro­pri­ate if you think you might want to install the En­ter­prise version at some point as you can upgrade later on. In contrast, it’s much more time-consuming to switch from the Community Edition to the En­ter­prise Edition.

We generally recommend using GitLab in a Linux en­vir­on­ment. Like Git, GitLab software is custom-made for Linux. You can install and use GitLab on Windows, albeit with re­stric­tions. If you want to do this, you can use a virtual machine that simulates a Linux en­vir­on­ment on the Windows computer. A simpler option is to install the GitLab Runner, which is required if you want to use con­tinu­ous in­teg­ra­tion func­tion­al­it­ies in GitLab.

In­stalling GitLab on your own server doesn’t pose any major chal­lenges if you have previous Linux ex­per­i­ence, but it’s re­l­at­ively time-consuming. In addition to the in­stall­a­tion itself, you have to factor in the time required for con­fig­ur­a­tion and regular main­ten­ance.

If you want to save yourself this effort, you can also install and use GitLab as Software-as-a-Service (SaaS) on a cloud server (many providers offer this service). This way you can deploy the software quickly without the need for complex in­stall­a­tion and con­fig­ur­a­tion. The GitLab Runner is usually already installed so that you can get started right away.

The advantage of manually in­stalling GitLab in your own server en­vir­on­ment is greater flex­ib­il­ity. You have complete freedom when it comes to in­stall­a­tion: You can make your own decisions about backups, updates or ad­di­tion­al resources, and install what you need for a specific ap­plic­a­tion. Nev­er­the­less, the cloud solution is appealing, es­pe­cially if your system ad­min­is­trat­or tends to deal with heavy workloads.

To install GitLab on a Linux server, you first need Git software. We explain how to install Git on a server in our Git tutorial. Next, you should download the GitLab omnibus package from the official GitLab website. This package contains all the necessary files and is re­com­men­ded for in­stalling GitLab on Linux.

Next, log in to the server as the root user and update the re­pos­it­ory (Ubuntu in this case) to receive all the necessary packages for GitLab. To do this, use the following commands:

Then install the packages as follows:

A con­fig­ur­a­tion screen appears during Postfix in­stall­a­tion. Select Internet site and enter the server domain name that you use to send and receive emails.

The next step is to install the GitLab Omnibus package. First, add the GitLab package re­pos­it­ory using the following command:

Then install GitLab using the apt command. In this example code, GitLab is installed in the Community Edition (CE):

Once the data has been entered, the server auto­mat­ic­ally downloads and installs the GitLab package. After the in­stall­a­tion has been confirmed, you should configure the main URL that you use to access the GitLab server.

Change the URL "https://GitLab.example.com" to the URL you actually use. To do this, go to the /etc/GitLab directory where the con­fig­ur­a­tion is located and edit the con­fig­ur­a­tion file GitLab.rb using the default vim text editor.

The commands look like this:

In the GitLab.rb file, look for line 9 (‘external_url’) and enter the desired URL. GitLab will start and configure the in­stall­a­tion at this URL.

When you open GitLab for the first time, you’ll be directed to a password reset screen. Set the password for the ad­min­is­trat­or; you’ll then be re­dir­ec­ted to the login screen. You can initially use the default user ‘root’ to log in. You can change the settings later in the profile settings.

GitLab itself cannot be installed on a Windows server, but you can use a GitLab Runner to access an existing GitLab in­stall­a­tion on a Linux server from Windows. This software is installed in Windows and is com­pat­ible with the con­tinu­ous in­teg­ra­tion func­tion­al­ity of GitLab (GitLab CI/CD). In this way, the runner can send requests and work orders to GitLab.

You need Git for Windows before you can install GitLab on a Windows server. You can download the software from the official website. You should also assign a unique password for the user account unless you are going to use the default system account.

You will need a token that grants the runner access to the GitLab instance. This access key can be found in the GitLab settings under Settings -> CI / CD.

Next, download the binary file (x86 or amd64) for the GitLab Runner for Windows and create a folder anywhere in your system, for example C:\GitLab-runner.

Paste the file into this folder and rename it to GitLab-runner.exe. Then open Windows Power­Shell (or Command Prompt) with advanced ad­min­is­trat­or access rights.

To register the GitLab runner, enter the following command in the command line:

Then enter the URL of the GitLab in­stall­a­tion (the following is just an example):

In the next window, enter the token in order to link the runner to the GitLab in­stall­a­tion. You can then define your own de­scrip­tion for the runner. This option can also be changed later in the GitLab interface. In the next window, you can define tags. These tags are useful if you want a runner to process several projects at the same time. You can use the tags to specify exactly which projects are assigned.

In the last step, you define the ‘executor’, meaning the en­vir­on­ment in which the runner runs, for example a Vir­tu­al­Box instance or a shell en­vir­on­ment. Shell is the easiest executor to configure and the default option when you register a GitLab Runner on Windows for the first time.

To install the GitLab Runner, you can either use the default system account or your own user account. In the Power­Shell or Command Prompt, navigate to the directory you created above and type the following commands one at a time:

After in­stalling GitLab, you can access the graphical user interface at the pre­vi­ously defined URL. To do this, you can use the browser of your choice and then log in as an ad­min­is­trat­or. The user name and the as­so­ci­ated password can be changed later in the Admin Area.

In the Admin Area, you can select the New User button to create the users who col­lab­or­ate on GitLab projects. To do this, you define a unique email address and log-in cre­den­tials for the user, and then assign the user to the desired project.

In the same area, you can also change user per­mis­sions by selecting ‘Edit’ and block or remove users. Note that blocking a user prevents them from logging in while keeping all data (such as commits) intact. Com­pletely removing a user also deletes the in­form­a­tion linked to the user. Therefore, always exercise caution when selecting this option.

The most important step is to create a new project. To do this, select the New project button. This will take to you the page for creating a new project. Enter the name of the project in the ‘Project name’ field. This field may not contain any special char­ac­ters or spaces. Under Vis­ib­il­ity level, you define which users have access to the project. GitLab dis­tin­guishes between the following levels:

• Private: Only you have access.
• Internal: Each logged-in user has access.
• Public: Any user can access the project without prior au­then­tic­a­tion.

After selecting the settings, create the project by selecting Create project. You can then link the project directly to a local Git re­pos­it­ory. To do this, select the ‘HTTPS’ option under the project name in the project view and copy the displayed commands to the command line.

In case you don’t have a local copy of the re­pos­it­ory on the server, you can add it now by entering the following command:

Once you’ve ini­tial­ised the re­pos­it­ory, you can view all in­form­a­tion about it on the project page. You can also view recent activ­it­ies and look at the commit history to see who made which changes to the code and when.

The easiest way to work together with other users on a GitLab project is to grant users direct push access to the re­pos­it­ory. To do this, add the users to a project as explained above and provide them with the ap­pro­pri­ate access rights.

Users with ‘developer’ au­thor­isa­tion or higher can move their commits and branches to the re­pos­it­ory without re­stric­tions. Al­tern­at­ively, you can also use merge requests, which allow you to control access more closely since the master branch is not edited directly. Instead, users can create branches, enter their commits and then make a merge request to connect the branch to the master (or another branch).

Users without access rights can also create forks, meaning they can edit their own copy of the project with pushed commits. They can then submit a merge request to re­in­teg­rate the fork into the main project. With this feature, the project owner has full control over what goes into the re­pos­it­ory, but he or she can also allow unknown users to make con­tri­bu­tions.