Install and run on GitLab CI/CD, Host, Linux and Buildah | CI/CD | Getting Started

Prepare the infrastructure

Requirements

GitLab;
Linux host to install the GitLab Runner, featuring:
- Bash;
- Git version 2.18.0 or above;
- GPG.

Installing the GitLab Runner

Follow official instructions to install the GitLab Runner on your dedicated host.

Setting up the build environment with Buildah

Follow these steps on the GitLab Runner host to install Buildah:

Install the Buildah package following the official instructions but avoid configuring it. If there are no ready-made Buildah packages for your distribution, refer to the following guidelines:

Installing Buildah manually

Install the packages for newuidmap and newgidmap.

Make sure that newuidmap and newgidmap have the proper permissions:

sudo setcap cap_setuid+ep /usr/bin/newuidmap
sudo setcap cap_setgid+ep /usr/bin/newgidmap
sudo chmod u-s,g-s /usr/bin/newuidmap /usr/bin/newgidmap

Install the package that provides the /etc/subuid and /etc/subgid files.
Make sure that the /etc/subuid and /etc/subgid files have a line similar to gitlab-runner:1000000:65536, where
- gitlab-runner — name of the GitLab Runner user;
- 1000000 — the first subUID/subGID in the range to be allocated;
- 65536 — subUIDs/subGIDs range size (min 65536).
Make sure there are no conflicts with other ranges, if any. Changing files may require a reboot. See man subuid and man subgid for details.

(Linux 5.12 and below) Install the package that provides the fuse-overlayfs utility.
Make sure that the /home/gitlab-runner/.local/share/containers path is created and the gitlab-runner user has read and write access.
The sysctl -ne kernel.unprivileged_userns_clone command should NOT return 0, otherwise run echo 'kernel.unprivileged_userns_clone = 1' | sudo tee -a /etc/sysctl.conf && sudo sysctl -p.
The sysctl -n user.max_user_namespaces command should return 15000 or more, otherwise run echo 'user.max_user_namespaces = 15000' | sudo tee -a /etc/sysctl.conf && sudo sysctl -p.
(For Ubuntu 23.10 and later) set values kernel.apparmor_restrict_unprivileged_unconfined and kernel.apparmor_restrict_unprivileged_userns to 0 with the command:{ echo "kernel.apparmor_restrict_unprivileged_userns = 0" && echo "kernel.apparmor_restrict_unprivileged_unconfined = 0";} | sudo tee -a /etc/sysctl.d/20-apparmor-donotrestrict.conf && sudo sysctl -p /etc/sysctl.d/20-apparmor-donotrestrict.conf

Installing werf

To install werf on the GitLab Runner host, run the following command:

curl -sSL https://werf.io/install.sh | bash -s -- --ci

Registering the GitLab Runner

Follow official instructions to register GitLab Runner in GitLab: set Shell as the executor. Once the registration is complete, you may want to perform additional GitLab Runner configuration.

Configuring the container registry

Enable garbage collection for your container registry.

Preparing the system for cross-platform building (optional)

This step only needed to build images for platforms other than host platform running werf.

docker run --restart=always --name=qemu-user-static -d --privileged --entrypoint=/bin/sh multiarch/qemu-user-static -c "/register --reset -p yes && tail -f /dev/null"

Configure the project

Configuring the GitLab project

Enable Require a successful pipeline for merge requests.
Enable the option to auto-cancel redundant pipelines.
Create and save the access token to clean up the no longer needed images from the container registry with the following parameters:
- Token name: werf-images-cleanup;
- Role: developer;
- Scopes: api.
Add the following variables to the project variables:
- werf version:
  - Key: WERF_VERSION;
  - Value: 2 stable;
- Access token to clean up the no longer needed images:
  - Key: WERF_IMAGES_CLEANUP_PASSWORD;
  - Value: <"werf-images-cleanup" access token you saved earlier>;
  - Protect variable: yes;
  - Mask variable: yes.
Add a scheduled nightly task to clean up the no longer needed images in the container registry by setting the main/master branch as the Target branch.

Configuring CI/CD of the project

This is how the repository that uses werf for build and deploy might look:

Extras:

Add authorization options for werf cleanup in the container registry by following instructions.