Własny GitLab Runner na VPS: wymagania, instalacja w Dockerze i zabezpieczenie

11 min. czytania

Część 1 serii self-hosted-ci-runners

  1. Część 1: Własny GitLab Runner na VPS: wymagania, instalacja w Dockerze i zabezpieczenie
  2. Część 2: Self-hosted runner GitHub Actions bez rozdawania roota

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ć. Trzymaj major.minor runnera w parze z wersją GitLaba; GitLab gwarantuje wsteczną zgodność między wydaniami minor. Ten poradnik przypina gitlab/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 concurrent razy najcięższy job. W tym repozytorium to test:php, który uruchamia npm 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:

yaml
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:

bash
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:

toml
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"
  • concurrent to globalny limit jednocześnie działających jobów; limit ogranicza jeden wpis [[runners]]. Dobierz je według zasady z sekcji o wymaganiach.
  • request_concurrency domyślnie wynosi 1. Przy tej wartości i limit = 2 runner 19.5.3 przy starcie loguje ostrzeżenie o long pollingu i sugeruje 2 do 4.
  • privileged = false zostawia 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_policy domyś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. Samo if-not-present pozwala 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_policies blokuje jobowi politykę, której nie ma na liście. allowed_images i allowed_services w ten sam sposób ograniczają obrazy i usługi, z wildcardami.
  • memory i cpus nie 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"] i DOCKER_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.sock do volumes jobów. Joby sterują wtedy demonem hosta: ich kontenery są rodzeństwem runnera, a docker rm -f w 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ę:

yaml
.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:

toml
[[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).

bash
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

Powiązane artykuły

Utrzymanie i rozwój

Chcesz uporządkować utrzymanie albo wdrożenia?

Pomagam stabilizować środowiska, układać proces wdrożeń i rozwijać istniejące systemy bez zatrzymywania pracy zespołu.

Komentarze (0)
Zaloguj się, aby dodać komentarz

Musisz być zalogowany, aby dodać komentarz.

Zaloguj się

Potrzebujesz kogoś, kto weźmie odpowiedzialność za kolejny krok?

Porozmawiajmy o Twoim projekcie i określmy zakres, który ma sens dla Twoich celów.