Translated using DeepL

Machine-translated page for increased accessibility for English questioners.

Page in original, Czech language.

GitLab FI

GitLab Continuous Integration

GitLab Continuous Integration (CI) is used to automate certain tasks during development in a repository, most commonly for automated unit testing. To use GitLab CI, you can configure your own physical or virtual machine (see Stratus.FI virtualisation). Alternatively, you can also use the faculty machine atgitlab-ci.fi.muni.cz.

Summary

The faculty’sgitlab-ci.fi uses the official GitLab Runner with container isolation via Docker. When a new job is launched (e.g. following a `git push ` to the repository), the GitLab Runner asks Docker to create a new container from the image specified in the repository’s `.gitlab-ci.yml` file. The repository is cloned into the container and the tasks described in the aforementioned file are run. Once complete, the container is terminated and the result is returned to GitLab, which displays it in the CI/CD section.

Configuring the project forgitlab-ci.fi.muni.cz

First, read the introductory information on using GitLab CI/CD. You will also need the documentation for.gitlab-ci.yml.

Selecting an image

The image to be used is specified in the.gitlab-ci.yml configuration as the value of the `image` key. The format is either `REPOSITORY:TAG ` or `REPOSITORY ` (the default tag is then `latest`). If you do not specify an image, `alpine:latest` will be used. 

image: maven:latest

Version selection

Docker image tags are not static; that is,X:3.0 is merely a symbolic name for a particular version of the image, and it may happen at any time that the repository maintainer changes the image to which the tag points. Image versioning and the meaning of the versions themselves depend on the maintainers of the individual Docker repositories; however, it is generally advisable to adhere to the principles of semantic versioning.

Where possible, opt for images with the most general major version (e.g. preferX:3 overX:3.5.0) so that your project has access to an image with security patches and bug fixes for the software used.

However,we do not recommend usinglatest for critical projects. This symbolic link usually points to the latest stable version of the image, but it may be updated without warning to a newer version that is not backwards compatible.

Tag settings

To prevent the machine from being overloaded with tasks from repositories that have their own CI set up,gitlab-ci.fi only accepts tasks from projects tagged withshared-fi, which can be configured as follows:

  • in Settings → General → Permissions, enable the ‘Pipelines’ option if it is not already enabled
  • in the.gitlab-ci.yml settings, add theshared-fi tag to each target, e.g.: 
    build:
  tags:
    - shared-fi

Artifact settings

For projects that generate artifacts, we recommend configuring CI so that GitLab automatically deletes them when newer ones are created.

If you do not configure this clean-up and the project’s artefacts start to take up GitLab’s disk space, they will be deleted by the administrators.

First, ensure within the project that GitLab retains the latest artefact:
Project → Settings → CI/CD → Artifacts → tick ‘Keep artefacts from most recent successful jobs’

Then, in `.gitlab-ci.yml `, add a setting that sets the lifespan of artefacts to a very short duration (less than 2 hours, e.g. 10 minutes). Set this for each job: `JOB`.
Thanks to the settings above, the most recent artefact will be retained even after its retention period has expired. 

‹JOB›:
  artifacts:
    …
    expire_in: 10 minutes

Examples

On the Faculty’s GitLab (FI), you can take a look at the project unix/ci-examples, where you’ll find examples of CI configurations for simple projects.

Your own GitLab Runner instance

You can also run your own group or project-specific GitLab Runner instance. The advantage of a custom GitLab Runner instance is usually a shorter wait time for a task to run, particularly when the faculty’s instances are busy. The disadvantage, however, is the need to manage your own or virtual hardware.

When configuring your own GitLab Runner instance, please follow these guidelines.

Limit the frequency of requests to GitLab to a maximum of 1 request per minute.

In the GitLab Runner configuration, the value ‘check_interval’ refers to the interval at which the Runner checks for available jobs for each project and group it serves, which, for a large number of projects, leads to unnecessary load.

Inconfig.toml, therefore, set the value for ‘check_interval ’ to at least ten times the number of projects and groups being served. Update this value every time you enable the Runner for another project or group.

For example, if you have a Runner for 2 groups and 3 projects, set the value to (2 + 3) × 10 = 50:
check_interval = 50

Failure to comply with these rules may result in your instance’s IP address being blocked by the firewall and restrictions on other services.

Container Registry

The Container Registry service allows users to store Docker images associated with a project, which can then be used in CI or other projects.

The images do not need to be related to the project’s content in any way. However, you will likely also have a `Dockerfile ` and other dependencies for the image, so we recommend creating a repository for these files, which will also keep the image version up to date.

You can connect to the Container Registry on the machinegitlab.fi.muni.cz and port5050.

Service configuration

  • Enabling the service

    In the project intended to host the built images, enable
    Settings → General → Visibility, project features, permissions → Container Registry.
    It is not necessary to enable this service for projects that only intend to use the image in CI.

  • Limit on the number of brands

    Images in Container Registry usually take up a lot of space. Frequent tag changes can quickly use up disk space, so enable automatic cleanup for the project:
    In Settings → Packages & Registries, enable the ‘Clean up image tags’ option. We also recommend changing the ‘Keep the most recent’ setting to ‘5 tags per image name’.

  • Access to the image

    Access to images is generally governed by the access rights for the parent project:
    • Private – Project members only
    • Internal – Only users logged into GitLab FI
    • Public – No restrictions
    Furthermore, access can be restricted via the above setting from ‘Everyone with access’ to ‘Only project members’.

Creating an image

Manually

The simplest way to build an image is to use a Docker or Podman instance on your own computer. This option is suitable for situations where the image does not change frequently and setting up automated builds using CI would be impractical.

The name of the image to be deployed to the GitLab Container Registry must begin with the domain and port in the formatgitlab.fi.muni.cz:5050, followed by the path to the project. For example, for the projecthttps://gitlab.fi.muni.cz/NAMESPACE/PROJECT.git, you can create images with names of the form

  • gitlab.fi.muni.cz:5050/NAMESPACE/PROJECT:TAG
  • gitlab.fi.muni.cz:5050/NAMESPACE/PROJECT/IMAGE:TAG
  • gitlab.fi.muni.cz:5050/NAMESPACE/PROJECT/NAME/IMAGE:TAG

In the directory containing Dockerfile or Containerfile build the image (using one of the formats above as the image name): 

    $ docker build -t gitlab.fi.muni.cz:5050/‹LOGIN›/‹PROJECT›:‹TAG› .

If you are happy with the image, you can upload it to Container Registry.

First, log in with your client. To log in, you can use a password (only possible if you haven’t enabled 2FA) or a GitLab access token, which must have at least the following permissions:read_registry andwrite_registry. 

    $ docker login --username ‹LOGIN› gitlab.fi.muni.cz:5050

Use your faculty login instead of‹LOGIN›. When prompted for a password, enter your password or token.

Then upload the image to Container Registry: 

    $ docker push gitlab.fi.muni.cz:5050/‹NAMESPACE›/‹PROJECT›:‹TAG›

Automatic image build in the faculty’s GitLab CI

The faculty’s GitLab CI has offered the option to build images since November 2025 using Rootless Docker-in-Docker.

In a project with an image source (typicallyDockerfile orContainerfile), add.gitlab-ci.yml. Tasks that wish to use Docker to build an image (i.e. those callingdocker build) must meet the following conditions:

  • They must use thedocker:cli ordocker:‹version›-cli image.
  • They must run thedocker:dind-rootless ordocker:‹version›-dind-rootless service.
  • It must have the environment variableDOCKER_HOST=unix:///runner/services/docker/docker.sock set.
  • It must have the tagshared-fi. If you come across a project with the tagshared-fi-dind, this is a tag from the testing phase; you do not need to correct it, but do not use it in new projects.

The same conditions apply to deployment as to manual builds, particularly regarding the image name. GitLab CI injects its own variables into the environment for authentication with the Container Registry (CI_REGISTRY,CI_REGISTRY_USER,CI_REGISTRY_PASSWORD). Before running `docker push `, simply execute this command: 

    echo "$CI_REGISTRY_PASSWORD" | docker login $CI_REGISTRY -u $CI_REGISTRY_USER --password-stdin
Never include your login details or tokens in.gitlab-ci.yml or anywhere else in the project!

You can find an example of the configuration in the ci-dind-example project on the faculty’s GitLab.

Automatic image build in your own CI

Before Rootless Docker-in-Docker was introduced to the faculty’s GitLab CI, this was the only way to automate the process. It may still be relevant for personal experimentation or for builds that are resource- or time-intensive; in other circumstances, we recommend using the faculty’s instance.

  • A virtual machine or a computer?

    For this task, we strongly recommend using a virtual machine on the Stratus.FI service. It should be sufficient to use the pre-installed virtual machine.

    Using your own computer is also possible. Please note, however, that in the event of a configuration error, there is a risk of privilege escalation or someone gaining control of your computer. The same risk applies to a virtual machine, although the scope of the problem is smaller in this case.

  • GitLab CI Runner

    Install GitLab Runner (→ Install on GNU/Linux for Linux).

  • Docker within Docker

    Configure the CI Runner to build Docker images according to the official guide. We recommend the Docker-in-Docker option.

  • Registration

    Register the Runner only for the project in which the images are to be built; see Project Runners.

  • Project security

    Ensure that only trusted users within the project (Owners, Maintainers) can trigger CI jobs. In particular, prevent untrusted users from creating a Merge Request with their own code that would trigger the job.

    See Protected Branches and the rules for.gitlab-ci.yml.

  • Location of .gitlab-ci.yml

    A potential attacker could change.gitlab-ci.yml at will and bypass the settings above. This is a serious issue, particularly for public and internal projects.

    This issue can be resolved by configuring the project so that.gitlab-ci.yml searches in a different private repository, where only trusted users can edit it. The local file will then be ignored. See Custom CI/CD configuration file → Custom CI/CD configuration file examples.

    Please note that setting `CODEOWNERS ` is not sufficient; it will only prevent an unwanted merge if the protected file has changed, but the CI tasks will still run.

If you build images infrequently, the safest option is to build the image locally.

Common issues and solutions

Stuck tasks

If, after configuring your project, you encounter the error ‘Job is stuck’, you have probably not included the ‘shared-fi ’ flag in the task configuration. Please check your settings following the procedure above.

Docker commands cannot be used in the job

If you encounter an error such as ‘dial tcp: lookup docker on 147.251.48.14:53: no such host ’, you are probably attempting to use the faculty CI Runner in privileged mode. This is only permitted if the conditions for automatic builds in the faculty GitLab CI are met. If you still believe this to be an error, please contact or the administrator at.