Własne runnery CI: Część 1 · Część 2
Pipeline na hostowanych runnerach GitLaba uruchamia każdy job na świeżej maszynie. Job czeka w kolejce, pobiera obraz, ściąga archiwum cache, wykonuje się i znowu wysyła cache. Na GitLab.com samo wykonanie jest rozliczane w compute minutes. Job deployu łączy się potem z Twoim serwerem z adresu, nad którym nie masz kontroli, więc port SSH musi być osiągalny z internetu. Plik .gitlab-ci.yml tej strony robi dokładnie to: szablon deployu uruchamia ssh-keyscan -p $SSH_PORT $SSH_HOST i scp z hostowanego runnera.
Runner na własnym VPS zmienia wszystkie trzy rzeczy: obrazy i cache zależności zostają ciepłe na lokalnym dysku, płacisz za serwer zamiast za minuty, a job deployu dociera do produkcji przez sieć prywatną. Ceną jest maszyna, która wykonuje kod pipeline'u z sekretami CI w środowisku. Izolacja i minimalne uprawnienia są więc częścią konfiguracji od pierwszego kroku.
Co zyskujesz, a co bierzesz na siebie
Zyskujesz ciepłe warstwy obrazów, wolumen cache, który przetrwa między jobami, brak rozliczania za minuty i dostęp do prywatnych hostów. Bierzesz na siebie serwer do łatania, dysk, który zapełnia się obrazami i wolumenami cache, wersję runnera do pilnowania razem z GitLabem oraz demona Dockera, który na tym hoście jest rootem. Jeśli nikt w zespole nie będzie tego robił co miesiąc, zostań na hostowanych runnerach.
Wymagania
- GitLab z tokenami uwierzytelniania runnera. Runnery tworzy się w UI i rejestruje tokenem z prefiksem
glrt-. Stare tokeny rejestracyjne wyłączono w GitLabie 17.0 i mają zostać usunięte w GitLabie 20.0, więc nowe instalacje nie powinny z nich korzystać. Trzymajmajor.minorrunnera w parze z wersją GitLaba; GitLab gwarantuje wsteczną zgodność między wydaniami minor. Ten poradnik przypinagitlab/gitlab-runner:alpine-v19.5.3, aktualne na 2026-11-10. - Linux z Docker Engine. GitLab nie podaje sztywnych liczb CPU i RAM. Strona wymagań wymienia, od czego zależy rozmiar: CPU i pamięć zużywane przez joby, liczba równoległych jobów, projektów i programistów. Rozsądny punkt wyjścia: dobierz maszynę pod
concurrentrazy najcięższy job. W tym repozytorium totest:php, który uruchamianpm run build, a potem Pest z--parallel. - Tylko wychodzący HTTPS. To runner otwiera połączenie: odpytuje GitLaba przez
POST /api/v4/jobs/request. Potrzebuje dostępu wychodzącego do instancji GitLaba i do rejestrów obrazów, z których korzystają joby. Nie potrzebuje żadnego portu przychodzącego, więc firewall może blokować cały ruch przychodzący poza Twoim SSH. - Osobna maszyna. GitLab zaleca hosta innego niż instancja GitLaba, a strona o bezpieczeństwie zaleca osobny segment sieci dla runnerów. Nie stawiaj runnera na produkcyjnym serwerze aplikacji: job, który ucieknie z kontenera, wyląduje obok produkcyjnej bazy.
Krok 1: utwórz runnera w UI
W projekcie wejdź w Settings > CI/CD, rozwiń Runners i wybierz Create project runner. Ustaw tagi, zdecyduj o Run untagged i utwórz runnera. GitLab pokaże token glrt- i polecenie rejestracji. Zapisz go w menedżerze haseł. Tagi, run untagged, flagę protected i maksymalny czas joba ustawia się teraz w UI. Z --token polecenie gitlab-runner register nie przyjmuje tych wartości z linii poleceń.
Krok 2: plik compose i rejestracja
Sam runner działa w kontenerze. Katalog konfiguracji jest zamontowany, żeby config.toml przetrwał aktualizacje, a socket Dockera, żeby runner mógł uruchamiać kontenery jobów:
services:
gitlab-runner:
image: gitlab/gitlab-runner:alpine-v19.5.3
restart: unless-stopped
volumes:
# tu leży config.toml z tokenem runnera: chmod 600, nigdy w gicie
- ./config:/etc/gitlab-runner
# pozwala runnerowi uruchamiać kontenery jobów na demonie Dockera tego hosta
- /var/run/docker.sock:/var/run/docker.sock
ports:
# metryki Prometheusa, dostępne tylko z tego hosta
- "127.0.0.1:9252:9252"
Zarejestruj runnera raz, jednorazowym kontenerem tej samej usługi, żeby wynik trafił do zamontowanego ./config:
export RUNNER_TOKEN='glrt-...' # z UI, nigdy w repozytorium
docker compose run --rm gitlab-runner register \
--non-interactive \
--url "https://gitlab.com" \
--token "$RUNNER_TOKEN" \
--executor docker \
--docker-image alpine:3.22 \
--description "vps-runner-1"
chmod 600 config/config.toml
docker compose up -d
Strona instalacji GitLaba ostrzega, że zamontowany socket daje kontenerowi runnera pełną kontrolę nad demonem Dockera na hoście. Można to przyjąć tylko dlatego, że na tym hoście nie działa nic innego.
Krok 3: opcje config.toml, które mają znaczenie
Rejestracja zapisuje minimalny plik. Doprowadź go do takiej postaci, a potem docker compose restart gitlab-runner:
concurrent = 2
check_interval = 3
listen_address = ":9252"
[[runners]]
name = "vps-runner-1"
url = "https://gitlab.com"
token = "glrt-REPLACE_ME"
executor = "docker"
limit = 2
request_concurrency = 2
output_limit = 8192
[runners.docker]
image = "alpine:3.22"
privileged = false
volumes = ["/cache"]
pull_policy = ["always", "if-not-present"]
allowed_pull_policies = ["always", "if-not-present"]
memory = "4g"
cpus = "2"
concurrentto globalny limit jednocześnie działających jobów;limitogranicza jeden wpis[[runners]]. Dobierz je według zasady z sekcji o wymaganiach.request_concurrencydomyślnie wynosi 1. Przy tej wartości ilimit = 2runner 19.5.3 przy starcie loguje ostrzeżenie o long pollingu i sugeruje 2 do 4.privileged = falsezostawia kontenery odizolowane. Strona GitLaba o bezpieczeństwie mówi, że job w trybie privileged może zdobyć roota na hoście.volumes = ["/cache"]trzyma lokalny cache w wolumenie Dockera między jobami.pull_policydomyślnie ma wartośćalways. Przy liście runner próbuje kolejnej polityki, gdy pobranie się nie uda, więc awaria rejestru nie zatrzymuje pipeline'u. Niezmienione warstwy i tak nie są pobierane drugi raz. Samoif-not-presentpozwala jobowi użyć zbuforowanego prywatnego obrazu bez poświadczeń, przed czym GitLab ostrzega na runnerach współdzielonych przez różnych użytkowników.allowed_pull_policiesblokuje jobowi politykę, której nie ma na liście.allowed_imagesiallowed_servicesw ten sam sposób ograniczają obrazy i usługi, z wildcardami.memoryicpusnie pozwalają jednemu rozbuchanemu jobowi zagłodzić drugiego.
Executor: docker, nie shell
Executor shell jest w trybie utrzymania. Używa hosta przy każdym buildzie, nie daje czystego środowiska per job, a jobom daje dostęp do plików użytkownika runnera. Strona GitLaba o bezpieczeństwie nazywa to wysokim ryzykiem dla hosta i sieci. Używaj executora docker: świeży kontener per job, usługi takie jak redis:latest z joba test:php w tym repozytorium i domyślnie brak dostępu do plików runnera.
Budowanie obrazów Dockera: najmniejsze uprawnienia, które wystarczą
Pipeline tej strony buduje tarball, a nie obraz, więc jego runner zostaje bez uprawnień privileged. Jeśli Twój pipeline robi docker build, są trzy drogi:
- Docker-in-Docker: usługa
docker:dind,privileged = true,volumes = ["/certs/client", "/cache"]iDOCKER_TLS_CERTDIR: "/certs". Każdy job dostaje własny demon. Dokumentacja GitLaba mówi, że tryb privileged wyłącza mechanizmy bezpieczeństwa kontenera i może skończyć się ucieczką z kontenera. - Podpięcie socketu: dodaj
/var/run/docker.sock:/var/run/docker.sockdovolumesjobów. Joby sterują wtedy demonem hosta: ich kontenery są rodzeństwem runnera, adocker rm -fw jobie może usunąć kontenery runnera. Traktuj to jak oddanie roota na hoście każdemu pipeline'owi. - Buildery bez demona: Buildah buduje obrazy OCI bez demona, a GitLab dokumentuje go z
quay.io/buildah/stable. Kaniko było typową odpowiedzią, ale Google zarchiwizował jego repozytorium 3 czerwca 2025, a dokumentacja GitLaba mówi teraz, że projekt nie jest utrzymywany. Sprawdź jego status upstream w dniu, w którym chcesz go wdrożyć, także jeśli chodzi o fork.
Jeśli potrzebujesz DinD, daj mu osobnego runnera: otagowanego, chronionego i najlepiej na osobnej VM.
Tagi, run untagged i chronione runnery
Tagi decydują, który runner weźmie job. Runner musi mieć każdy tag wymieniony w jobie. Runner, który nie uruchamia jobów bez tagów, zostawia je w stanie stuck. Dla tego repozytorium zarejestruj dwa runnery. Pierwszy uruchamia joby bez tagów, więc test:php, test:js, secrets:gitleaks i build nie wymagają zmian. Drugi ma tag deploy i jest oznaczony jako Protected, więc uruchamia joby tylko na chronionych gałęziach i tagach. Szablon deployu dostaje jedną linię:
.deploy_template: &deploy_template
stage: deploy
image: alpine:3.19
tags: [deploy]
needs: [build]
deploy_prod działa na main, a deploy_dev na develop, więc obie gałęzie muszą być chronione, inaczej deploy_dev będzie czekał na runnera w nieskończoność. Oznacz też SSH_KEY i ENV_FILE jako zmienne chronione, żeby nigdy nie trafiły na niechronioną gałąź. Gdy runner deployu stoi w tej samej sieci prywatnej co produkcja, SSH_HOST może być adresem prywatnym, a publiczny port SSH można zamknąć.
Cache: najpierw lokalny wolumen, S3 przy drugim runnerze
Przy executorze Docker bez rozproszonego cache wpisy cache: lądują pod /cache w wolumenach Dockera na hoście runnera. Szybko, ale cache należy do tego jednego runnera. To repozytorium wylicza klucz cache z composer.lock i package-lock.json, więc pierwszy pipeline po zmianie pliku lock jest zimny na każdym runnerze. Gdy pojawia się drugi runner albo autoscaler, przenieś cache do magazynu zgodnego z S3:
[[runners]]
name = "vps-runner-1"
[runners.cache]
Type = "s3"
Shared = true
[runners.cache.s3]
ServerAddress = "s3.example.com"
BucketName = "gitlab-runner-cache"
BucketLocation = "eu-central-1"
AccessKey = "REPLACE_ME"
SecretKey = "REPLACE_ME"
Lokalne wolumeny i obrazy rosną bez końca. GitLab dostarcza clear-docker-cache do usuwania nieużywanych wolumenów runnera i sugeruje uruchamianie go co tydzień z crona. Skrypt nie usuwa obrazów; robi to docker system prune. Każde czyszczenie sprawia, że następny pipeline jest zimny, więc planuj je poza godzinami pracy.
Zmierz to na własnym pipeline
Liczby z cudzego pipeline'u niewiele mówią o Twoim, więc zmierz własny. API jobów zwraca dla każdego joba queued_duration (czas czekania na runnera) i duration (czas wykonania).
curl --silent --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
"https://gitlab.com/api/v4/projects/$PROJECT_ID/pipelines/$PIPELINE_ID/jobs" \
| jq -r '.[] | [.name, .runner.description, .queued_duration, .duration] | @tsv'
Porównaj trzy pipeline'y na tym samym commicie: na hostowanych runnerach, na Twoim runnerze zaraz po zmianie pliku lock (zimny cache) i ponowienie na Twoim runnerze (ciepły cache). queued_duration pokazuje kolejkę, w której już nie czekasz. Różnica duration między zimnym a ciepłym przebiegiem pokazuje, co daje lokalny cache.
Aktualizacje i monitoring
Podbijaj przypięty tag, gdy GitLab przechodzi na nowe wydanie minor, wstrzymaj runnera w UI, żeby żaden job nie był w trakcie, a potem docker compose pull && docker compose up -d. System i Docker Engine łataj w tym samym rytmie.
Z ustawionym listen_address runner wystawia metryki Prometheusa pod /metrics, domyślnie na porcie 9252. Endpoint nie ma uwierzytelniania. Dlatego plik compose publikuje go tylko na 127.0.0.1. Zbieraj metryki Prometheusem na tym samym hoście albo przez sieć prywatną, ustaw alert na niedostępny target i obserwuj gitlab_runner_errors_total. Lista runnerów w GitLabie pokazuje też czas ostatniego kontaktu każdego runnera.
Kiedy nie stawiać własnego runnera
- Mało buildów. Kilka pipeline'ów w tygodniu mieści się w hostowanych runnerach.
- Nikt nie odpowiada za maszynę. Niełatany runner z sekretami deployu jest gorszy niż wolne CI.
- Projekty publiczne i forki. Kod pipeline'u od obcych ludzi wykonuje się na Twoim serwerze i może odczytać to, co może odczytać job. Użyj hostowanych runnerów albo efemerycznych VM.
- Skoki równoległości albo wiele platform. Jeden VPS daje stałą liczbę slotów na jednej architekturze. Executory z autoskalowaniem istnieją, ale to osobny projekt.
Jeśli chcesz, żebym postawił i zabezpieczył taki runner dla GitLaba Twojego zespołu, zobacz moją ofertę. Ten tekst dobrze łączy się z twardymi bramkami CI z wpisu o bramkach jakości.
Następna część: Runnery GitHub Actions na własnym serwerze bez oddawania roota.
Źródła
- Dokumentacja GitLab Runnera: Run GitLab Runner in a container (dostęp: 2026-11-10)
- Dokumentacja GitLab Runnera: Registering runners (dostęp: 2026-11-10)
- Dokumentacja GitLaba: Migrating to the new runner registration workflow (dostęp: 2026-11-10)
- Dokumentacja GitLaba: Manage runners (zakresy runnerów) (dostęp: 2026-11-10)
- Dokumentacja GitLaba: Configuring runners (chronione runnery, tagi, limity czasu) (dostęp: 2026-11-10)
- Dokumentacja GitLab Runnera: przegląd i zgodność wersji (dostęp: 2026-11-10)
- Dokumentacja GitLab Runnera: System requirements and supported platforms (dostęp: 2026-11-10)
- Dokumentacja GitLab Runnera: Executors (dostęp: 2026-11-10)
- Dokumentacja GitLab Runnera: Docker executor (dostęp: 2026-11-10)
- Dokumentacja GitLab Runnera: Advanced configuration (dostęp: 2026-11-10)
- Dokumentacja GitLaba: Use Docker to build Docker images (dostęp: 2026-11-10)
- Dokumentacja GitLaba: Use Docker-in-Docker (dostęp: 2026-11-10)
- Dokumentacja GitLaba: Use kaniko to build Docker images (removed) (dostęp: 2026-11-10)
- Repozytorium GoogleContainerTools/kaniko (zarchiwizowane) (dostęp: 2026-11-10)
- Dokumentacja GitLab Runnera: Security for self-managed runners (dostęp: 2026-11-10)
- Dokumentacja GitLab Runnera: Monitor GitLab Runner usage (dostęp: 2026-11-10)
- Dokumentacja GitLaba: Jobs API (dostęp: 2026-11-10)
- Docker Hub: tagi gitlab/gitlab-runner (dostęp: 2026-11-10)