GitLab CI self-hosted runner: instalace na VPS

GitLab CI self-hosted runner: instalace a první pipeline na VPS

Ve třetí části jsme připojili vlastního agenta ke GitHub Actions a dovedli řetězec k deployi na produkci přes SSH. Nyní tu samou cestu procházíme na GitLab CI: instalujeme GitLab Runner na VPS, registrujeme jej v projektu, píšeme první .gitlab-ci.yml a končíme tím samým scénářem deploye. Scénář se opakuje záměrně, aby byl rozdíl mezi platformami vidět na stejné úloze, a ne na dvou různých příkladech.

Rozdíl se ukáže hlubší než syntaxe. V GitLabu se pipeline staví na stage, úloha se ve výchozím nastavení vykonává v kontejneru a volba executoru určuje, jak přesně je váš kód izolován. Tyto tři věci ovlivňují architekturu řešení silněji než vzhled YAML.

1.1 Co je potřeba na startu

• projekt na GitLabu: v cloudu na gitlab.com nebo ve vlastní instalaci;
• VPS s Ubuntu 22.04 či 24.04 a přístupem přes SSH;
• role Maintainer nebo Owner v projektu: níže než ona není stránka s runnery dostupná.

Stejně jako agent GitHubu nepotřebuje GitLab Runner otevřené příchozí porty. Sám se obrací na GitLab na portu 443 a drží spojení, čekaje na úlohy. Proto runner klidně žije uvnitř uzavřeného okruhu vedle produkce.

1.2 gitlab.com a vlastní runner: kombinace, kterou lidé často opomíjejí

Rozšířené nedorozumění: aby člověk získal self-hosted CI na GitLabu, musí prý zvednout celý GitLab u sebe. Tak to není. Cloudový gitlab.com a vlastní runner se kombinují bez omezení: repozitář, rozhraní, merge request a stránka pipeline zůstávají v cloudu a sestavení se vykonává na vašem serveru, s vašimi zdroji a vaším přístupem do produkční sítě.

Tři scénáře, ve kterých je takové schéma na místě:

• Kvóta minut se vyčerpává. Cloudové minuty se počítají a docházejí, vlastní server se platí fixně nezávisle na počtu sestavení.
• Jsou potřeba nestandardní zdroje. Hodně RAM pro těžké sestavení, GPU pro testy modelů, specifický hardware, který v cloudových plánech není.
• Deploy jde do uzavřené sítě. Cloudový runner se tam nedostane, váš stojí uvnitř.

Vlastní instalace GitLabu (self-managed) je samostatné řešení s jinými důvody: požadavky na uchovávání kódu, regulatorní omezení, práce bez přístupu k internetu. Lze ji udělat později a nezávisle, protože konfigurace pipeline a runneru se při stěhování nemění.

2. Architektura GitLab CI

Tři pojmy, na kterých stojí vše další: konfigurační soubor, hierarchie pipeline a runner jako samostatný proces.

2.1 .gitlab-ci.yml: jeden soubor v kořeni repozitáře

Na rozdíl od GitHub Actions s adresářem .github/workflows/ a libovolným počtem souborů hledá GitLab jeden soubor: .gitlab-ci.yml v kořeni. Popisuje celou pipeline projektu.

Omezení se snímá dvěma mechanismy. První je include: konfiguraci lze rozdělit na části a připojovat je z jiných souborů, z jiných projektů nebo podle URL.

include:
  - local: '/ci/build.yml'
  - project: 'company/ci-templates'
    ref: main
    file: '/deploy/ssh.yml'
  - template: Security/SAST.gitlab-ci.yml

Druhý jsou šablony úloh přes kotvy YAML a klíč extends, které odstraňují opakování uvnitř souboru. Dohromady dávají to samé, čeho se v GitHubu dosahuje několika workflow a znovupoužitelnými akcemi, jen vstupním bodem zůstává jeden soubor.

Cesta k souboru se mění v Settings → CI/CD → General pipelines → CI/CD configuration file. Tam lze také uvést soubor z jiného projektu, pokud je konfigurace centralizovaná.

2.2 Stages → Jobs → Scripts

Stage je logická skupina úloh a hlavní odlišnost od GitHub Actions. Stage se vykonávají postupně v pořadí, vyhlášeném v stages. Následující startuje tehdy, když se předchozí dokončila zcela a úspěšně.

Job je úloha uvnitř stage. Úlohy jedné stage se vykonávají paralelně na různých runnerech, proto stage trvá tak dlouho, jak nejpomalejší úloha v ní.

Script je seznam příkazů shellu, které úloha vykonává. Zde je odlišnost patrná: v GitHubu bývá krok hotovou akcí přes uses, v GitLabu je úloha téměř vždy příkazy. Místo marketplace akcí se používají image kontejnerů a připojené šablony.

stages: [build, test, deploy]

build-app:      stage: build   →┐
                                 │ stage build
build-docs:     stage: build   →┘ (paralelně)
                                 ↓
unit-tests:     stage: test    →┐
                                 │ stage test
lint:           stage: test    →┘ (paralelně)
                                 ↓
deploy-prod:    stage: deploy  →  stage deploy

Přísnou posloupnost stage lze obejít klíčem needs. Staví graf závislostí nad stage: úloha startuje hned po těch, na kterých závisí, aniž by čekala na zbytek své stage. Na velkých pipeline to patrně zkracuje celkový čas.

deploy-staging:
  stage: deploy
  needs: [build-app]     # nečeká na build-docs a na celou stage test
  script:
    - ./scripts/deploy.sh staging

2.3 GitLab Runner jako samostatný proces

GitLab Runner je samostatný program, který nezávisí na GitLabu a nemusí ani stát vedle něj. Jeho práce vypadá takto: jednou za několik sekund se dotazuje GitLabu přes API, zda je úloha pro jeho štítky a úroveň registrace. Po získání úlohy připraví prostředí, vykoná příkazy, proudem odevzdává logy a vrací stav.

Registrace bývá na třech úrovních:

Klíčová vlastnost, kterou GitHub Actions nemá: jeden runner vykonává několik úloh současně. Parametr concurrent v konfiguraci zadává, kolik úloh proces runneru vykonává paralelně na všech zaregistrovaných runnerech dohromady, proto jeden VPS nahrazuje několik samostatných agentů.

3. Instalace GitLab Runneru na VPS

3.1 Instalace balíčku

Nejpohodlnější cesta je oficiální repozitář balíčků:

# Debian / Ubuntu
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
sudo apt install gitlab-runner

# RHEL / Rocky / AlmaLinux
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.rpm.sh" | sudo bash
sudo yum install gitlab-runner

Balíček hned vytváří systémového uživatele gitlab-runner, konfiguraci v /etc/gitlab-runner/config.toml a systemd službu s automatickým spuštěním. Tedy krok se zformováním služby, který se v GitHub Actions dělal zvlášť přes svc.sh, je zde už proveden.

Alternativou je binárka, když jsou repozitáře nedostupné nebo je potřeba konkrétní verze. Soubor pro potřebnou architekturu berte ze stránky releasů GitLab Runneru: přímé adresy S3 bucketu se pravidelně mění a příkazy z cizích návodů rychle zastarávají.

sudo curl -L --output /usr/local/bin/gitlab-runner "<odkaz ze stránky releasů>"
sudo chmod +x /usr/local/bin/gitlab-runner
sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash
sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
sudo gitlab-runner start

Kontrola po instalaci:

gitlab-runner --version
sudo systemctl status gitlab-runner

3.2 Registrace runneru

Od verze 16.0 GitLab přešel na registraci přes token, vytvořený v rozhraní. Cesta: Settings → CI/CD → Runners → New project runner. Tam se zadávají štítky (tags), volba pro spouštění úloh bez štítků a volitelný popis, načež GitLab ukáže token typu glrt-....

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

Starý způsob s --registration-token a klíčem --tag-list se v dokumentaci ještě vyskytuje, ale v současných verzích nefunguje: štítky se teď zadávají v rozhraní při vytváření tokenu, a ne v příkazu.

Po registraci se runner objeví v seznamu se stavem online a jeho nastavení ulehnou do /etc/gitlab-runner/config.toml:

concurrent = 4
check_interval = 3

[[runners]]
  name = "vps-build-01"
  url = "https://gitlab.com/"
  token = "glrt-XXXXXXXXXXXXXXXX"
  executor = "docker"
  [runners.docker]
    image = "alpine:latest"
    privileged = false
    volumes = ["/cache"]

Soubor se načítá znovu bez restartu služby: po úpravě se změny aplikují samy. Parametr concurrent zadává počet paralelních úloh na celého agenta a začínat se vyplatí počtem jader děleným dvěma.

3.3 Executor: shell nebo docker

Executor určuje, kde přesně se příkazy úlohy vykonávají. To je hlavní rozhodnutí při nastavování a měnit jej potom není pohodlné.

Rozdělení vychází jednoduše. Docker se bere ve výchozím nastavení pro sestavení a testy: prostředí je popsané image v repozitáři, úlohy nezanechávají stopy, verze jazyka se mění jedním řádkem. Shell zůstává pro úlohy deploye, které potřebují přístup k samotnému hostu: klíče v ~/.ssh, nastavené rsync a ansible, přístup k lokálním socketům.

Tyto dva režimy si nekonkurují. Pracovní schéma jsou dva runnery na jednom VPS: jeden s executorem docker a štítkem build, druhý s executorem shell a štítkem deploy. Registrují se samostatnými příkazy register a žijí v jednom config.toml dvěma bloky [[runners]].

4. První .gitlab-ci.yml

4.1 Stage

Soubor začíná výčtem stage. Pořadí v seznamu je zároveň pořadí vykonávání:

stages:
  - build
  - test
  - deploy

Úloha bez klíče stage se dostane do stage test. Je to výchozí chování, které občas přináší překvapení, proto je lepší stage uvádět výslovně.

4.2 Základní úloha

stages: [build, test, deploy]

default:
  image: node:20
  tags: [self-hosted, docker]
  interruptible: true

variables:
  npm_config_cache: "$CI_PROJECT_DIR/.npm"

build:
  stage: build
  script:
    - npm ci --cache .npm --prefer-offline
    - npm run build
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - .npm/
  artifacts:
    paths:
      - dist/
    expire_in: 1 week

lint:
  stage: test
  script:
    - npm ci --cache .npm --prefer-offline
    - npm run lint

unit-tests:
  stage: test
  script:
    - npm ci --cache .npm --prefer-offline
    - npm test -- --ci
  artifacts:
    when: always
    reports:
      junit: reports/junit.xml

Co je zde důležité:

• tags je obdoba runs-on v GitHubu. Úloha půjde na runner, který má všechny vyjmenované štítky. Nesoulad zde je nejčastější příčina úlohy, která uvázla ve stavu pending.
• default zadává společná nastavení pro všechny úlohy, aby se image a tags neopakovaly v každé z nich.
• interruptible: true dovoluje rušit zastaralá spuštění, když do větve přiletěl novější commit. Spolu se zapnutou volbou projektu je to obdoba concurrency v GitHub Actions.
• artifacts: reports je vestavěný mechanismus, který v GitHubu není: GitLab report rozebere a ukáže výsledky testů přímo v merge requestu.

4.3 Pravidla spouštění: rules místo only

Klíč only/except stále funguje, ale vývoj byl zastaven a v nové konfiguraci se používá rules:

deploy-production:
  stage: deploy
  script:
    - ./scripts/deploy.sh
  rules:
    # nespouštět pro změny pouze v dokumentaci
    - if: $CI_COMMIT_BRANCH == "main"
      changes:
        paths: ["docs/**/*", "*.md"]
      when: never
    # v main s ručním potvrzením
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual
      allow_failure: false
    # ve zbylých případech úloha v pipeline není
    - when: never

Pravidla se kontrolují shora dolů, uplatní se první, které se shodlo. Hodnota when: manual vytváří úlohu s tlačítkem spuštění a allow_failure: false ji dělá blokující: dokud není tlačítko stisknuto, pipeline se nepovažuje za dokončenou. To je ten ruční krok Continuous Delivery.

4.4 Artifacty mezi úlohami

Artifacty se v GitLabu předávají mezi stage automaticky: úloha stage deploy dostává artifacty všech předchozích stage bez výslovného stahování. V GitHub Actions jsou k tomu potřeba samostatné kroky upload-artifact a download-artifact.

build:
  stage: build
  artifacts:
    paths: [dist/]
    expire_in: 1 week

deploy:
  stage: deploy
  script:
    - ls dist/          # soubory jsou už na místě
  # omezit výčet: vzít artifacty pouze jedné úlohy
  dependencies: [build]

Klíč dependencies se vyplatí nastavovat vědomě. Bez něj úloha táhne artifacty všech předchozích stage a na velké pipeline jsou to desítky zbytečných megabajtů na každou úlohu.

5. CI/CD Variables

V GitLabu není samostatné úložiště secrets jako Secrets v GitHubu. Místo toho jsou proměnné s příznaky, které určují úroveň ochrany.

5.1 Kde proměnné žijí

Cesta: Settings → CI/CD → Variables. Každá proměnná má klíč, hodnotu, typ (Variable nebo File) a sadu příznaků.

Typ File řeší úlohu, která se v GitHubu řeší ručně: GitLab položí hodnotu do dočasného souboru a do proměnné dosadí cestu k němu. Pro SSH klíče a konfigurace to odstraňuje kroky s echo do souboru a zároveň problémy se zalomeními řádků.

5.2 Protected a Masked: rozdíl

Dva příznaky řeší různé úlohy a lidé je pletou neustále.

Hlavní věc zde: Masked bez Protected nechrání před ničím vážným. Kdokoli, kdo může vytvořit větev, do ní napíše úlohu s cat po proměnné v base64 a získá hodnotu s obejitím maskování. Ochranu dává právě Protected spolu s nastavením chráněných větví v Settings → Repository → Protected branches.

Maskování má technické požadavky: hodnota od 8 znaků, bez mezer a zalomení řádků, pouze znaky z omezené sady. Víceřádkový SSH klíč zamaskovat nelze, a právě proto se pro něj bere typ File spolu s příznakem Protected.

5.3 Proměnné na úrovni skupiny

Pokud se několik projektů deployuje na tu samou infrastrukturu, je lepší držet proměnné na úrovni skupiny: Group → Settings → CI/CD → Variables. Dědí je všechny projekty skupiny a změna se dělá na jednom místě.

Pořadí priority při stejných jménech, od nejvyšší k nejnižší:

1. proměnné zadané při ručním spuštění pipeline;
2. proměnné projektu;
3. proměnné skupiny (vnořená skupina má prioritu nad rodičovskou);
4. proměnné instance;
5. proměnné z .gitlab-ci.yml.

Praktický závěr: společné hodnoty držte ve skupině a jednotlivé projekty ať přepisují to, co se u nich liší, tím samým jménem. Konfigurace v .gitlab-ci.yml přitom zůstává stejná pro všechny.

Ještě jedna úroveň jsou Environments se scope: jedna proměnná DEPLOY_HOST má různé hodnoty pro staging a production a úloha dostává potřebnou přes klíč environment. Logika je ta samá jako u Environment secrets z předchozí části.

6. Praktický příklad: deploy na server přes SSH

6.1 Ten samý scénář

Podmínky zcela opakují příklad ze třetí části: po push do main se projekt sestaví, artifact jede na produkční server přes rsync, služba se restartuje, načež se ověřuje health-check. Na serveru už je uživatel deploy bez práv root, klíč je vázán parametrem from na adresu runneru a restart služby je povolen bodově přes sudoers.

Proměnné v Settings → CI/CD → Variables:

• SSH_PRIVATE_KEY — typ File, příznak Protected. Typ File zde odstraňuje veškerou ruční práci se zalomeními řádků.
• SSH_KNOWN_HOSTS — typ File, Protected. Obsahem je výstup ssh-keyscan -H your-server.example.com.
• DEPLOY_HOST — obyčejná proměnná s adresou serveru.

6.2 Plný .gitlab-ci.yml

stages: [build, test, deploy]

default:
  interruptible: true

variables:
  npm_config_cache: "$CI_PROJECT_DIR/.npm"

build:
  stage: build
  image: node:20
  tags: [self-hosted, docker]
  script:
    - npm ci --cache .npm --prefer-offline
    - npm run build
  cache:
    key:
      files: [package-lock.json]
    paths: [.npm/]
  artifacts:
    paths: [dist/]
    expire_in: 1 week

test:
  stage: test
  image: node:20
  tags: [self-hosted, docker]
  script:
    - npm ci --cache .npm --prefer-offline
    - npm run lint
    - npm test -- --ci
  artifacts:
    when: always
    reports:
      junit: reports/junit.xml

deploy-production:
  stage: deploy
  tags: [self-hosted, shell]      # executor shell: je potřeba přístup k hostu
  environment:
    name: production
    url: https://app.example.com
  dependencies: [build]
  timeout: 10 minutes
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual
      allow_failure: false
  before_script:
    # varianta 1, typ proměnné File: GitLab už položil klíč do dočasného souboru
    - chmod 600 "$SSH_PRIVATE_KEY"
    # varianta 2, klíč v obyčejné proměnné — jako v GitHub Actions:
    # - install -m 700 -d ~/.ssh
    # - install -m 600 /dev/null ~/.ssh/deploy_key
    # - echo "$SSH_PRIVATE_KEY_RAW" > ~/.ssh/deploy_key
    # - echo "$SSH_KNOWN_HOSTS_RAW" > ~/.ssh/known_hosts
  # after_script:
  #   je potřeba pouze pro variantu 2: typ File maže platforma
  #   - rm -f ~/.ssh/deploy_key
  after_script:
    # shell executor uchovává pracovní adresář mezi úlohami: klíč uklízíme výslovně
    - shred -u "$SSH_PRIVATE_KEY" 2>/dev/null || rm -f "$SSH_PRIVATE_KEY"
  script:
    - |
      rsync -az --delete \
        -e "ssh -i $SSH_PRIVATE_KEY -o UserKnownHostsFile=$SSH_KNOWN_HOSTS" \
        dist/ deploy@$DEPLOY_HOST:/var/www/app/
    - |
      ssh -i "$SSH_PRIVATE_KEY" -o UserKnownHostsFile="$SSH_KNOWN_HOSTS" \
        deploy@$DEPLOY_HOST "sudo systemctl restart app.service"
    - |
      for i in $(seq 1 10); do
        code=$(curl -s -o /dev/null -w "%{http_code}" https://app.example.com/health || true)
        [ "$code" = "200" ] && exit 0
        sleep 3
      done
      echo "Služba po deployi neodpovídá"
      exit 1

V úloze deploye jsou záměrně ukázány dvě varianty práce s klíčem. První, funkční ve výchozím nastavení, se opírá o typ proměnné File: GitLab sám vytváří dočasný soubor a uklízí jej při čištění pracovního adresáře úlohy, proto kroky s echo do souboru chybí. Protože shell executor uchovává pracovní adresář mezi spuštěními, klíč se uklízí výslovně v after_script. Druhá, zakomentovaná, opakuje přístup ze třetí části: klíč leží v obyčejné proměnné, soubor se vytváří ručně a uklízet se musí už ~/.ssh/deploy_key. Bude se hodit při migraci z GitHub Actions, když se konfigurace přenáší tak, jak je, a syntaxe se mění postupně.

Rozdíl zde není v možnostech platforem, ale v tom, kdo vykonává rutinní práci: typ File snímá vytváření souboru a práci se zalomeními řádků, a úklid zůstává na vás v obou variantách. Na trvalém runneru to má praktickou váhu, protože zapomenutý krok čištění nechává privátní klíč dostupný pro následující úlohu.

Klíč environment dává ještě jeden efekt kromě scope proměnných. GitLab vede historii deployů na stránce Deployments → Environments: je vidět, který commit je teď na produkci, kdy se tam dostal a kdo úlohu spustil. Tam je také tlačítko pro návrat k předchozímu úspěšnému deployi, které prostě znovu spustí tu samou úlohu se starým commitem.

7. Závěr

Prošli jsme tu samou cestu jako ve třetí části, ale na GitLab CI. Hlavní z praxe:

• Cloudový GitLab a vlastní runner se kombinují volně. Zvedat self-managed GitLab kvůli self-hosted CI není potřeba.
• Executor je hlavní rozhodnutí při nastavování. Docker pro sestavení a testy, shell pro deploy, oba na jednom serveru s různými štítky.
• Stage zadávají pořadí, needs jej zrychluje. Graf závislostí odstraňuje čekání tam, kde není potřeba.
• Masked bez Protected není ochrana. Secret uzavírá právě příznak Protected spolu s chráněnými větvemi.
• Typ File odstraňuje ruční práci s klíči. Dočasný soubor vytváří a maže platforma, proto je nemožné zapomenout klíč uklidit.

Rozdíl oproti GitHub Actions se skládá ve srozumitelný obraz. GitLab dává více vestavěného: stage, reporty testů v merge requestu, historii deployů s návratem zpět, paralelní úlohy na jednom agentovi. GitHub dává více hotového zvenčí: marketplace akcí uzavírá typické kroky jedním řádkem. První je cennější pro složité pipeline, druhé pro rychlý start.

Co dál v sérii

V páté části uděláme krok, po kterém ven nevychází nic: Gitea Actions, kde git platforma a pipeline žijí na jednom vašem serveru. Syntaxe tam téměř opakuje GitHub Actions, proto se konfigurace ze třetí části přenášejí téměř bez úprav, ale server nyní drží jak git platformu, tak pipeline, proto jsou požadavky na zdroje a administraci jiné. Srovnání všech tří platforem s odpovědí na otázku, co volit pro konkrétní podmínky, čeká v šesté části.

Časté dotazy