GitLab Runner saját szerveren: telepítés és beállítás

A GitLab CI/CD-jobokat nem a GitLab maga futtatja, hanem egy külön program, a GitLab Runner. A GitLab.com ad közös (shared) runnereket, ezek ingyenes csomagban havi korlátozott számú compute minute-ot jelentenek, saját telepítésű GitLabhoz pedig eleve neked kell runnert állítanod. Saját runnerrel a jobok a te gépeden futnak: annyi erőforrással, amennyit adsz neki, a belső hálózatod eléréséhez, és percdíj nélkül. Ebben a cikkben egy Debian- vagy Ubuntu-szerverre telepítünk GitLab Runnert Docker executorral, és beregisztráljuk egy projekthez.

Milyen gépre telepítsd?

A runnernek nem kell erős gép, de a jobok (build, tesztek, Docker-image-ek építése) annál több erőforrást kérnek. Egy kisebb csapatnak jó kiindulás:

  • 2–4 vCPU, 4–8 GB memória, 50–100 GB SSD (a Docker-image-ek és a gyorsítótár hamar helyet foglalnak),
  • Debian 12/13 vagy Ubuntu 24.04/26.04 LTS,
  • külön virtuális gép, nem az éles alkalmazásszerver, és ne is LXC-konténer: a Docker egy virtuális gépben működik kiszámíthatóan. Az LXC és a KVM alapú virtualizáció különbségéről a tárhelymárkánk, az aWh blogján írtunk.

A runner kifelé kapcsolódik a GitLabhoz (HTTPS-en kérdezi le, van-e futtatandó job), ezért nem kell rá bejövő portot nyitni. Elég, ha eléri a GitLab-példányt.

Az executor kiválasztása

Az executor határozza meg, hol és hogyan fut egy job. A leggyakoribbak:

Executor Hol fut a job? Mikor jó?
shell közvetlenül a runner gépén, a gitlab-runner felhasználóval egyszerű telepítő szkriptek egy dedikált gépen
docker minden job egy friss Docker-konténerben a legtöbb esetben, ez az alapértelmezett választásunk
kubernetes podokban egy Kubernetes-klaszterben ha már van klaszter, és skálázni kell
docker-autoscaler igény szerint indított felhős gépeken változó, nagy terhelésnél

A Docker executor előnye, hogy minden job tiszta környezetben indul, a szükséges eszközöket a job által megadott image hozza, és a jobok nem szemetelik tele a runner gépét. Mi is ezt állítjuk be.

1. Docker telepítése

A Docker executorhoz Docker kell a gépre. A hivatalos tárolóból történő telepítést az aWh tudásbázisában írtuk le lépésről lépésre. Ellenőrzés:

sudo docker run --rm hello-world

2. A GitLab Runner telepítése

A GitLab saját csomagtárolót ad, a telepítő szkript ezt veszi fel a rendszerre. A dokumentáció azt javasolja, hogy futtatás előtt nézd át a szkriptet:

curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" -o script.deb.sh
less script.deb.sh
sudo bash script.deb.sh
sudo apt install gitlab-runner

gitlab-runner --version
systemctl status gitlab-runner

RHEL-alapú rendszeren (AlmaLinux, Rocky Linux) a script.rpm.sh szkript és a dnf install gitlab-runner parancs a megfelelő.

A runner verziója lehetőleg egyezzen a GitLab fő- és alverziójával. A GitLab.com mindig a legfrissebb kiadást futtatja (tegnap, szeptember 17-én jelent meg a 19.4), ehhez a csomagtárolóból mindig a legújabb runner települ. Saját GitLab mellett a runnert a GitLab frissítésével együtt frissítsd.

3. A runner létrehozása a GitLabban

A runnereket ma már a GitLab felületén hozod létre, és egy runner authentication tokent kapsz hozzá, amely glrt- előtaggal kezdődik. A régi, projekt- vagy csoportszintű registration token elavult, a GitLab a tervek szerint a 20.0-s verzióban távolítja el; új runnerhez már ne használd.

Projektszintű runnerhez:

  1. Nyisd meg a projektet, majd Settings › CI/CD, és nyisd le a Runners részt.
  2. Válaszd a Create project runner gombot.
  3. Add meg a címkéket (tags), például docker, linux. Ezekkel tudod a .gitlab-ci.yml-ben megmondani, mely jobok fussanak ezen a runneren. Ha címke nélküli jobokat is futtatna, jelöld be a Run untagged jobs opciót.
  4. Adj meg egy leírást, majd Create runner.
  5. A következő oldalon megkapod a regisztrációs parancsot a tokennel. A tokent csak rövid ideig látod, ezért azonnal használd fel.

Csoportszintű runnert a csoportban a Build › Runners, a teljes példányra szólót az Admin › CI/CD › Runners menüben hozhatsz létre.

A címkék, a futtatható jobok köre és a maximális futási idő az új folyamatban a GitLab felületén állítható, nem a regisztrációs parancsban.

4. Regisztráció a szerveren

sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com" \
  --token "glrt-..." \
  --executor "docker" \
  --docker-image "alpine:latest" \
  --description "docker-runner-01"

Saját GitLab esetén a --url a saját példányod címe. Ellenőrzés:

sudo gitlab-runner list
sudo gitlab-runner verify

A projekt Settings › CI/CD › Runners oldalán a runner mellett zöld jelzésnek kell megjelennie.

5. A config.toml finomhangolása

A beállítások a /etc/gitlab-runner/config.toml fájlban vannak. Egy jól használható kiindulás:

concurrent = 4          # egyszerre ennyi job futhat a gépen
check_interval = 3

[[runners]]
  name = "docker-runner-01"
  url = "https://gitlab.com"
  token = "glrt-..."
  executor = "docker"
  [runners.docker]
    image = "alpine:latest"
    privileged = false
    pull_policy = ["if-not-present"]
    volumes = ["/cache"]
    shm_size = 268435456

A concurrent értékét a gép erőforrásaihoz igazítsd: egy 4 vCPU-s gépen 2–4 párhuzamos job reális. A runner a változásokat magától észleli, de egy sudo gitlab-runner restart sem árt.

Docker-image építése a pipeline-ban

Ha a jobokban Docker-image-et építesz, két út van. A Docker-in-Docker (docker:dind szolgáltatás) privileged = true beállítást igényel, ami a jobnak gyakorlatilag root-jogot ad a runner gépén. A gazdagép Docker-socketjének becsatolása (/var/run/docker.sock) ugyanilyen kockázatos. Biztonságosabb alternatíva a rootless image-építés, például a Buildah vagy a BuildKit rootless módja. Privilegizált runnert csak olyan projektekhez rendelj, amelyekben megbízol.

6. Az első job

A .gitlab-ci.yml a projekt gyökerében:

teszt:
  image: php:8.4-cli
  tags:
    - docker
  script:
    - php -v
    - php -l index.php

Push után a Build › Pipelines oldalon látod, hogy a job a saját runneren fut-e.

Biztonság és karbantartás

  • Ne futtass idegen kódot shell executorral. Aki pipeline-t indíthat, az a shell executoron a runner gépén futtat parancsokat.
  • Védett runner, védett változók. A telepítést végző runnereket jelöld protected-nek, így csak védett ágak (például main) pipeline-jai használhatják, és a titkos változók sem kerülnek ki egy tetszőleges ágról.
  • Egy runner, egy cél. Az éles telepítéshez hozzáférő runner legyen külön a fejlesztői jobokat futtatótól.
  • Takarítás. A Docker-image-ek és a gyorsítótár hetek alatt megtöltik a lemezt. Egy heti docker system prune ezt megoldja; ütemezni egy systemd timerrel vagy egy crontab-bejegyzéssel lehet; a crontab szintaxisát az aWh tudásbázisában írtuk le.
  • Frissítés. A runnert a rendszerfrissítésekkel együtt frissítsd (sudo apt update && sudo apt install gitlab-runner).

Ha több runnert vagy több környezetet kezelsz, a runner gépét is érdemes kódból felhúzni: a virtuális gépet például Terraformmal vagy OpenTofuval, a telepítést és a config.toml-t Ansible-lel.

CI/CD-környezetek, GitLab-runnerek és telepítési folyamatok kiépítésében és üzemeltetésében is segítünk; erről a Felhő és DevOps oldalon olvashatsz.

Beszéljünk a projektedről

Írd le röviden, miben segíthetünk, és a lehető leghamarabb válaszolunk.

Kapcsolatfelvétel