login | rules | SSH | basics | sharing | e-mail replies | groups | CI | references

GitLab

GitLab is a web manager of Git reposiories similar to the well known GitHub service. In addition to repository management (repositories are called projects here) GitLab can do Wiki and Issue tracking.

Login

If you have an active account at the Faculty of Informatics, you can log in via LDAP authentication at the following URL:

https://gitlab.fi.muni.cz/

Enter your faculty login and password; the account will be created automatically after the first time you log in.

External accounts

There is a special type of account in GitLab that cannot own nor create its own projects, but can only contribute to projects that it has been explicitly granted access to. These accounts are called external. They are intended to, for instance, share projects with researchers and colleagues from other institutions or enable external opponents or consultants to review a thesis project.

External accounts cannot be created in GitLab FI directly, but faculty employees (members of fi-int group) can create, block or delete external accounts in the external account management application within Faculty administration.

Account validity

A GitLab account connected with your faculty account is valid only if the faculty account is active and unblocked. Should the faculty account be blocked or its validity have expired, all access to GitLab including SSH keys will be blocked as well.

Usage rules

  • you may not change your name even though GitLab allows it
  • you may not change the group path
  • repositories are not designated to store large files
  • the total size limit for all repositories is 1.5 GB (the size of individual repositories may be reduced by using ProjectSettingsHousekeeping)
  • make sure you follow the operating rules

SSH key

If you wish to work with a repository on your personal computer without the need to enter your password every time, you can upload the public SSH key in your profile. Follow the instructions. Here are tips only for UN*X systems.

How to create the SSH key

The ssh-keygen program may ask you to enter your password while creating the key. This is not mandatory: it is simpler to use the key with no password, however, the version with a password is safer.

Using the key with no password

You can use the following command to test the key functionality

ssh -i $path_to_the_PRIVATE_key git@gitlab.fi.muni.cz

The command output should be similar to:

Welcome to GitLab,(Name, Surname)
Connection to gitlab.fi.muni.cz closed.

Add the following lines to ~/.ssh/config (the file may not exist yet):

Host gitlab gitlab.fi.muni.cz
    HostName gitlab.fi.muni.cz
    IdentityFile path_to_the_PRIVATE_key

Individual lines are explained in the manual for ssh_config(5). You can try for yourself that the ssh git@gitlab command has an identical output to that noted above even without the key in the command arguments.

Using a key with a password

If you use this type of key as if it had no password, each GitLab operation will request the key password, which brings almost no benefit compared to regular login. Using the SSH agent, you will be able to unlock the key once and use it repeatedly:

ssh-agent $SHELL
ssh-add ~/.ssh/id_gitlab

The first command starts the agent, which, in turn, runs the new shell from the $SHELL variable. If your shell does not define the variable, enter the program path instead (e.g. /bin/sh). By terminating the shell you terminate the agent as well. Detailed information on commands is available in the instruction manual for ssh-agent(1) and ssh-add(1).

Please note that in the older version of the manual and on various discussion forums, you can find a procedure that makes use of eval $(ssh-agent -c) or a similar command. We do not recommend you use this procedure because it does not ensure the agent is terminated correctly.

Usage basics

Documentation on GitLab functions is available at help. We strongly recommend the following

Repository sharing

If you wish to allow access to other people outside of the project's “visibility” (Private, Internal or Public), you can set them as project members, see adding members.

If you wish to make a private or internal project accessible to a person who does not possess a faculty account, and the person only needs access the project to download it (i.e., he or she does not need access to Issues, wiki etc.), you can use Deploy keys (actually a read-only access to the project via the SSH key). If access to other services is required, or the ability to contribute to the project, the project must be made public or an external account must be created for the person concerned (place a request with administrators).

E-mail responses

The faculty GitLab features the Reply by E-mail function, which allows users to respond to comments in "issues" and "milestones" directly via e-mail. To use the function properly, several rules must be observed:

  • respond directly to the delivered mail via Reply function, do not compose a new e-mail
  • respond only above any citation, or—and this is advisable—delete any citations; GitLab may not eliminate citations correctly
  • if you sign your emails digitally, it is better not to add your signature to your GitLab responses

You can use Markdown in your emails and add attachments which will be displayed as attachment to your response in GitLab.

Groups

The feature to create your own groups is disabled in GitLab so that no collision with synchronized groups occurs. If you need to create your own group or wish to allow group synchronization, contact administrators.

If you become a member of a group, GitLab will send you an e-mail notification.

Guidelines for synchronized group owners

In your request to have a group created, indicate

  • the initial owner of the group, provided the group does not have an administrator who is on the faculty administration
  • default rights for members

For student subject groups, we recommend the Reporter rights, and for others the Developer rights. Rights may be modified in GitLab separately for individual users.

Groups synchronized with faculty administration are subject to special limitations to Owner rights. The synchronization script grants this right only to administrators. If you grant this right to a regular member, he or she will lose it after any synchronization.

Group setup

If you were granted group owner rights, GitLab will allow you to change the group settings. You can change the name or description but never change the path. It is not technically possible to prohibit this option in GitLab, nevertheless you can cause conflicts during the synchronization of new groups.

Groups are implicitly synchronized with the Private visibility. This setting may be changed to Internal or Public in SettingsGroup Visibility.

GitLab Continuous Integration

GitLab Continuous Integration (CI) aims to automate some of the tasks regarding the project, usually unit testing. In order to host a GitLab CI worker (called runner) it is possible to configure your own machine or a virtual one. Another way is to use already configured gitlab-ci.fi.muni.cz.

Overview

Faculty machine gitlab-ci.fi uses GitLab Runner with container isolation service Docker. After recieving a new task (e.g. after git push), GitLab Runner requests Docker to create a new container from an image specified in .gitlab-ci.yml. This file must exist in the root of the repository. The project is then cloned into the container and goals specified in the aforementioned file are run. Finally, the container is destroyed and the result is returned back to GitLab, which displays it in the CI/CD dashboard.

Project configuration to use gitlab-ci.fi.muni.cz

First of all, please read Getting started with GitLab CI/CD. Then you should get familiar with the .gitlab-ci.yml configuration file.

The GitLab Runner service is configured not to install all requested Docker images, bun only to use already installed ones. This constraint should prevent disk space exhaustion due to uncontrolled installation of various Docker images.

Currently the following DockerHub images are available:

Repozitář Značky
official alpine latest 3.8 3.7
official gcc latest 8.2 8 7.3 7
official haskell latest 8.4 8.2 8
official maven 3.5-jdk-10 3-jdk-10 3.5-jdk-9 3-jdk-9 latest 3.5-jdk-8 3-jdk-8 3.5-jdk-7 3-jdk-7
official openjdk 11-jdk 11 latest 10-jdk 10 9-jdk 9 8-jdk 8
official python latest 3.7 3.6 3
official ruby latest 2.5 2.4 2
jhasse/clang-tidy latest
amardikian/clang-3.8 latest
rsmmr/clang latest

The latest tag refers to the same version as the tag that follows it.

You can declare which image your jobs will use in .gitlab-ci.yml file using the image key. Expected values if either of for REPOSITORY:TAG or REPOSITORY (which will use the latest as a default). If no image is specified, the GitLab CI will use alpine:latest.

image: maven:latest

Please use images with the latest tag where possible, or at least the least specific version (e.g. 3-jdk-8 instead of 3.5.0-jdk-8). Otherwise your CI might stop working if administrators update available images and remove older ones to save disk space.

To avoid accepting tasks from projects that use their own runners, gitlab-ci shared runner will only accept tasks with the shared-fi tag:

  • in SettingsGeneralPermissions ensure that Pipelines feature is enabled
  • in file .gitlab-ci.yml in the root of the repository add shared-fi tag to each goal, e.g.:
    build:
      tags:
        - shared-fi
      ...

Please have a look at our repository unix/ci-examples where you can find example configurations of .gitlab-ci.yml.

Installation of additional Docker images

You may request administrators to install additional Docker images at unix@fi.muni.cz. Please include a simple description of how you are going to use the image.

If you need to install a customized image not available at DockerHub, please include the Dockerfile along with all files that are referenced from the Dockerfile. Administrators will build the image and install it into the Docker service.

Other links and instruction manuals