Autor: [Robert Zasilny](/autorzy/robert-zasilny) Ekspert bezpieczeństwa i compliance · Zweryfikowano Kwiecień 2026

1.  [Strona główna](/) ›
2.  [Baza wiedzy](/baza-wiedzy/) ›
3.  GitLab Runner self-hosted

# GitLab Runner self-hosted: od instalacji do produkcyjnego pipeline

Opublikowano: 9 kwietnia 2026 · Kategoria: DevOps

GitLab Runner to agent CI/CD, który wykonuje joby zdefiniowane w pliku `.gitlab-ci.yml`. Możesz korzystać z runnerów SaaS udostępnianych przez GitLab.com (2000 minut/miesiąc za darmo) albo postawić własnego runnera na VPS — co jest tańsze przy intensywnym CI i daje pełną kontrolę nad środowiskiem. W tym artykule pokażemy pełny proces: instalację, wybór executora, rejestrację, stages, artifacts i cache.

## Instalacja GitLab Runner na Ubuntu

GitLab Runner jest dostępny jako pakiet .deb dla Ubuntu/Debian. Oficjalne repozytorium GitLab ma zawsze najnowszą stabilną wersję, więc lepiej używać go niż Snap czy apt z default repozytoriów.

```
# Dodaj oficjalne repozytorium GitLab
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash

# Zainstaluj runner
sudo apt-get install gitlab-runner

# Uruchom jako serwis
sudo systemctl enable gitlab-runner
sudo systemctl start gitlab-runner

# Sprawdz wersje
gitlab-runner --version

# Status serwisu
sudo systemctl status gitlab-runner
```

Po instalacji runner działa jako serwis systemd, a konfiguracja znajduje się w `/etc/gitlab-runner/config.toml`. Domyślny użytkownik to `gitlab-runner`, który ma własny katalog domowy i nie powinien być rootem.

## Shell executor vs Docker executor

Wybór executora to najważniejsza decyzja przy konfiguracji runnera. Shell executor wykonuje komendy bezpośrednio w shellu użytkownika gitlab-runner — jest najszybszy, ale nie daje izolacji. Docker executor tworzy osobny kontener dla każdego joba — wolniejszy, ale zapewnia czyste środowisko i łatwy rollback.

Cecha

Shell executor

Docker executor

Szybkość startu

Natychmiast

2-5 sekund (pull image)

Izolacja

Brak

Pełna (container)

Konflikty wersji

Tak (global install)

Nie (per image)

Bezpieczeństwo

Niskie

Wysokie

Cleanup

Ręczny

Automatyczny

## Rejestracja runnera

Po instalacji runnera musisz go zarejestrować w GitLab. W GitLab idź do **Settings > CI/CD > Runners** i skopiuj token rejestracyjny. Rejestracja jest interaktywna, ale możesz też przekazać wszystkie parametry w linii komend (np. w skrypcie provisioningu).

```
# Rejestracja non-interactive z docker executor
sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --registration-token "TWOJ_TOKEN" \
  --executor "docker" \
  --docker-image "alpine:latest" \
  --description "vps-runner-1" \
  --tag-list "docker,vps,linux" \
  --run-untagged="true" \
  --locked="false" \
  --access-level="not_protected"

# Lista zarejestrowanych runnerow
sudo gitlab-runner list

# Weryfikacja polaczenia
sudo gitlab-runner verify
```

## Stages, artifacts i cache w .gitlab-ci.yml

Plik `.gitlab-ci.yml` definiuje pipeline: stages (fazy), joby w każdym stage, zmienne, cache, artifacts i warunki uruchomienia. Stages są wykonywane sekwencyjnie, a joby w obrębie tego samego stage — równolegle (jeśli masz wystarczającą liczbę runnerów).

```
stages:
  - test
  - build
  - deploy

variables:
  NODE_VERSION: "20"

# Cache wspoldzielony miedzy jobami
.node_cache: &node_cache
  cache:
    key:
      files:
        - pnpm-lock.yaml
    paths:
      - node_modules/
      - .pnpm-store/

test:unit:
  stage: test
  image: node:${NODE_VERSION}
  <<: *node_cache
  script:
    - corepack enable
    - pnpm install --frozen-lockfile
    - pnpm test:unit
  artifacts:
    when: always
    reports:
      junit: reports/junit.xml
    expire_in: 1 week

build:production:
  stage: build
  image: node:${NODE_VERSION}
  <<: *node_cache
  script:
    - pnpm install --frozen-lockfile
    - pnpm build
  artifacts:
    paths:
      - dist/
    expire_in: 1 day
  only:
    - main

deploy:production:
  stage: deploy
  image: alpine:latest
  before_script:
    - apk add --no-cache openssh-client rsync
  script:
    - rsync -az dist/ deploy@vps:/var/www/app/
  only:
    - main
  when: manual
```

## Optymalizacja wydajności runnera

Self-hosted runner pozwala na agresywne optymalizacje, które nie są dostępne na runnerach SaaS. Pierwszą rzeczą jest ustawienie `concurrent` w `/etc/gitlab-runner/config.toml` — ile jobów może być wykonywanych równolegle. Domyślnie 1, co dla maszyny z 4 vCPU jest marnowaniem zasobów.

Druga optymalizacja to konfiguracja wolumenów cache dla Dockera. Domyślnie każdy job zaczyna z pustym volume, ale możesz zmapować wolumen hosta, żeby cache npm/pnpm/composer był utrzymywany między runami. Dodaj w sekcji runners.docker: `volumes = ["/cache", "/var/cache/pnpm:/root/.pnpm-store"]`.

Trzecia to użycie BuildKit w Dockerze — włącz `DOCKER_BUILDKIT=1` w variables pipeline, a czas buildów skróci się o 30-60%. Dodatkowo BuildKit obsługuje parallel layer builds i inline cache mount, czego klasyczny docker build nie potrafi.

## Najczęstsze pytania

Czym różni się shell executor od docker executor w GitLab Runner? +

Shell executor wykonuje joby bezpośrednio w systemie hosta (szybciej, ale brak izolacji). Docker executor uruchamia każdy job w osobnym kontenerze (izolacja, czyste środowisko, łatwy rollback). Dla CI produkcyjnego zalecany jest docker executor.

Ile zasobów potrzebuje self-hosted GitLab Runner? +

Minimum to 1 vCPU i 2 GB RAM dla małych projektów. Dla średnich CI (Node.js, Docker build) warto mieć 2 vCPU i 4 GB RAM. Duże projekty z równoległymi jobami wymagają 4+ vCPU, 8+ GB RAM i szybkiego dysku SSD/NVMe.

Jak zarejestrować runnera do projektu? +

W GitLab idź do Settings > CI/CD > Runners, skopiuj token rejestracyjny, a następnie uruchom gitlab-runner register, podaj adres instancji, token i wybierz executor (docker/shell). Runner pojawi się na liście dostępnych dla projektu.

Co przechowywać w artifacts a co w cache? +

Artifacts to wyniki buildów przekazywane między jobami w tym samym pipeline (np. zbudowany frontend, raporty testów). Cache to pliki przyspieszające kolejne uruchomienia (node\_modules, vendor/). Artifacts są wersjonowane i pobierane przez UI, cache jest efemeryczny.

## Sprawdź oferty pasujące do tego scenariusza

Poniżej masz szybkie przejścia do ofert i stron z kodami rabatowymi tam, gdzie są dostępne.

Contabo

Mocny VPS z 4+ vCPU i NVMe SSD — idealny do self-hosted GitLab Runner z docker executor.

VPS

[Aktywuj rabat →](/out/contabo)

#Reklama · link partnerski

[Zobacz kod rabatowy →](/kody-rabatowe/contabo)

LH.pl

Hosting SSH przydatny do testów pipelineów bez własnego VPS-a.

Hosting

[Aktywuj rabat →](/out/lh-pl)

#Reklama · link partnerski

[Zobacz kod rabatowy →](/kody-rabatowe/lh-pl)

Mikrus

Tani VPS do eksperymentów z GitLab Runner i docker-in-docker.

Dev/Test

[Aktywuj rabat →](/out/mikrus)

#Reklama · link partnerski

[Zobacz kod rabatowy →](/kody-rabatowe/mikrus)

## Powiązane strony

-   [GitHub Actions: deployment na VPS](/baza-wiedzy/github-actions-deployment-vps)
-   [Docker na VPS: instalacja i konfiguracja](/baza-wiedzy/docker-na-vps)
-   [Capistrano: deployment Rails i PHP](/baza-wiedzy/capistrano-deployment-rails)
-   [Wszystkie artykuły](/baza-wiedzy/)