From db247605a96c36eab97c06faf82c130bf302372e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gabriel=20N=C3=BCtzi?= Date: Sun, 23 Nov 2025 16:56:26 +0100 Subject: [PATCH] fix: documentation --- nixos/doc/manual/redirects.json | 9 ++- nixos/modules/services/misc/gitlab.md | 82 ++++++++++++++++++++++++++- 2 files changed, 86 insertions(+), 5 deletions(-) diff --git a/nixos/doc/manual/redirects.json b/nixos/doc/manual/redirects.json index 4eb7dc94da62..fe45e035d41b 100644 --- a/nixos/doc/manual/redirects.json +++ b/nixos/doc/manual/redirects.json @@ -38,9 +38,6 @@ "module-boot-plymouth-tpm2-totp-quick-start-enable": [ "index.html#module-boot-plymouth-tpm2-totp-quick-start-enable" ], - "module-services-gitlab-runner": [ - "index.html#module-services-gitlab-runner" - ], "sec-override-nixos-test": [ "index.html#sec-override-nixos-test" ], @@ -1197,6 +1194,12 @@ "module-services-gitlab-maintenance-rake": [ "index.html#module-services-gitlab-maintenance-rake" ], + "module-services-gitlab-runner": [ + "index.html#module-services-gitlab-runner" + ], + "ex-gitlab-runner-podman": [ + "index.html#ex-gitlab-runner-podman" + ], "module-forgejo": [ "index.html#module-forgejo" ], diff --git a/nixos/modules/services/misc/gitlab.md b/nixos/modules/services/misc/gitlab.md index 5fbb66cf100b..589407cc0b39 100644 --- a/nixos/modules/services/misc/gitlab.md +++ b/nixos/modules/services/misc/gitlab.md @@ -124,6 +124,84 @@ A list of all available rake tasks can be obtained by running: $ sudo -u git -H gitlab-rake -T ``` -## Runner {#module-service-gitlab-runner} +## Runner {#module-services-gitlab-runner} -See [section](#module-services-gitlab-runner). +GitLab Runner is a CI runner which is an executable which you can host yourself. +A Gitlab pipeline runs operations over a Gitlab Runner. These can include +building an executable, running a test suite, pushing a docker image, etc. The +Gitlab Runner receives jobs from Gitlab which it then dispatches to the +configured executors +([`docker` (`podman`), or `shell` or `kubernetes`](https://docs.gitlab.com/runner/executors)). + +The +[services.gitlab-runner.services](https://search.nixos.org/options?query=services.gitlab-runner.services) +documents a number of typical setups to configure multiple runners with +different executors. + +The [below example](#ex-gitlab-runner-podman) gives a **more elaborate** example how to +configure a Gitlab Runner with caching and reasonably good security practices. + +::: {#ex-gitlab-runner-podman .example} + +## Example Gitlab Runner with `podman` and Nix Store Caching + +The [VM tested podman-runner](https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/continuous-integration/gitlab-runner/runner.nix) (a NixOS Module for reuse) configures a Gitlab Runner with the following +features: + +- The executor is `podman` which gives you better additional safety than + `docker`. That means every job is run in a `podman` container. + +- The following container **images** are built with Nix: + + **Container Images for Gitlab Jobs**: + - `local/alpine`: An image based on Alpine with a Nix installation + (variable `alpineImage`). + - `local/ubuntu`: An image based on Ubuntu with a Nix installation + (variable `ubuntuImage`). + - `local/nix`: An image based on Nix which only comes with `nix` + installed(variable `nixImage`). + + **Images for VM Setup**: + - `local/nix-daemon-image`: An image with with a Nix daemon which is + used to share the `/nix/store` across jobs (variable `nixDaemonImage`). + - `local/podman-daemon-image`: An image with a `podman` running as a daemon which is + used to run `podman` inside the above job containers images + (variable `podmanDaemonImage`). + +- Every job container runs in a `podman` container instance based by default on + `ubuntuImage`. A pipeline job can override this with `image: local/alpine`. + - Each job container will have the `/nix/store` mounted from a container + `nix-daemon-container` (see registration flags + `--docker-volumes-from "nix-daemon-container:ro"`). + + The `nix-daemon-container` is a single container instance of a + `nixDaemonImage`. This enables caching of `/nix/store` paths across all jobs + in **all** runners. This makes **the host VM's `/nix/store` independent of the + Nix store used in the jobs**, which is good. + + ::: {.note} + **Security:** If you don't want this you need multiple `nixDaemonImage` + containers for each registered runner (`gitlab-runner.services.`). + ::: + + - Each job container will have the `/run/podman/podman.sock` socket mounted from the + `podman-daemon-container`. + + The `podman-daemon-container` is a single container of a `podmanDaemonImage` which runs + `podman` as a daemon. Job containers can use this daemon to spawn nested containers as well (podman-in-podman). **Keep in mind that `bind` mounts are local to the `podman-daemon-container`** and can be be worked around with a `podman volume create ` and manual copy-to/copy-from this volume ``. + + If you only need to build containers you don't need this feature (`podman-daemon-container`), see below point. + + Container configuration files (`auxRootFiles`) are copied to all containers to + ensure `podman` works inside the job containers. + + - The job containers do **not** mount the `podman` socket from the host (NixOS + VM) mounted for security reasons. + + ::: {.note} + Building container images with `buildah` (stripped + `podman` for building images) inside a job which runs `alpineImage` + is still possible. + ::: + +:::