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:
- Nyisd meg a projektet, majd Settings › CI/CD, és nyisd le a Runners részt.
- Válaszd a Create project runner gombot.
- 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. - Adj meg egy leírást, majd Create runner.
- 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 pruneezt 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.