Self-hosted CI/CD: koncepce, architektura a runnery

Self-hosted CI/CD: koncepce, architektura a runnery

V první části série jsme rozebrali, co je CI/CD, z čeho se skládá pipeline a čím se Continuous Delivery liší od Continuous Deployment. Zůstala tam jedna otázka bez odpovědi: a na jakém stroji se vlastně provádějí všechny tyto buildy a testy?

Ve výchozím nastavení je odpověď prostá: na cizím. Napíšete runs-on: ubuntu-latest, a GitHub pro vás zvedne virtuální stroj, prožene na něm váš kód a potom ho zničí. Je to pohodlné přesně do chvíle, kdy začnou překážet limity, cena nebo požadavky na to, kde přesně se má váš kód provádět. Tehdy na scénu přichází self-hosted runner: vlastní stroj, který dělá tutéž práci, ale pod vaší kontrolou.

Tento článek není o instalaci (to bude v částech 3, 4 a 5 pro GitHub Actions, GitLab CI a Gitea Actions), ale o architektuře: jak je runner uspořádán, proč nepotřebuje otevřené porty, jaké bývají executory, kolik zdrojů je reálně potřeba a jaké chyby v nastavení mění váš runner v otevřené dveře do infrastruktury.

1.1 Cloudové runnery: jak to funguje ve výchozím nastavení

Když se pipeline provádí na infrastruktuře platformy, každá úloha dostává čistý virtuální stroj s předinstalovanou sadou nástrojů: kompilátory, Docker, typické SDK, cache populárních image. Po dokončení úlohy je stroj zničen spolu se všemi daty.

Výhody jsou zřejmé: nic není třeba administrovat, prostředí je vždy čisté, izolace mezi úlohami je úplná, platforma sama aktualizuje image. Pro většinu projektů to stačí a začínat stojí za to právě cloudovými runnery. Ale model má čtyři omezení, na která dřív nebo později narazí rostoucí tým.

• Limity minut. Bezplatná kvóta je konečná a neroste tak rychle jako počet pipeline.
• Cena při velkém objemu. Minuty nad kvótu se platí a účet roste lineárně s počtem buildů.
• Uzavřený okruh. Kód a secrets se provádějí na cizí infrastruktuře. Pro část projektů je to nepřijatelné podle smlouvy nebo předpisu.
• Fixní zdroje. Standardní runner jsou 2 vCPU a několik gigabajtů RAM. Pokud build vyžaduje GPU, 32 GB paměti nebo procesor ARM, standardní konfigurace nevyhovuje.

1.2 Self-hosted: vlastní server provádí úlohy

Self-hosted runner je proces-agent, který spouštíte na vlastním serveru, VPS nebo dokonce na stroji v kanceláři. Registruje se ve vašem projektu na GitHubu nebo GitLabu a začíná odtud dostávat úlohy. Všechno ostatní se nemění: pipeline se popisuje týmž YAML, logy a statusy jsou vidět v témže rozhraní, tlačítka a notifikace fungují jako dřív.

Mění se jen jedno: řádek s volbou runneru v konfigu pipeline.

# GitHub Actions: místo ubuntu-latest
jobs:
  build:
    runs-on: [self-hosted, linux, x64]

# GitLab CI: úloha půjde na runner s odpovídajícím tagem
build:
  tags:
    - self-hosted

Je důležité chápat hranici odpovědnosti. Platforma si nechává u sebe: repozitář, rozhraní, frontu úloh, uchovávání secrets, artefakty. Vy na sebe berete jen provádění: stroj, jeho zdroje, aktualizace OS, izolaci a bezpečnost. Není to nahrazení GitHubu nebo GitLabu vlastním serverem, ale přenesení jedné konkrétní části systému blíž k sobě.

2. Kdy je self-hosted opodstatněný

Vlastní runner není „správnější“ a není to „dospělá úroveň“. Je to kompromis: dostáváte kontrolu a předvídatelnou cenu, zato na sebe berete administraci. Níže jsou čtyři situace, ve kterých je tato výměna výhodná.

2.1 Vyčerpané bezplatné minuty

To je nejčastější důvod. Kvóty aktuální k polovině roku 2026 vypadají takto:

Dva detaily, které se pravidelně stávají překvapením. První: v GitHubu se kvóta spotřebovává s násobitelem podle OS, tedy build na Windows sežere dvakrát více kvóty za tentýž čas, a na macOS desetkrát. Druhý: v GitLabu se bezplatné minuty počítají na celou skupinu nejvyšší úrovně, a ne na uživatele či projekt, proto tým pěti lidí a tým padesáti startují ze stejného čísla.

2.2 Uzavřený okruh

Druhý důvod nemá nic společného s penězi. Jsou projekty, u kterých se kód fyzicky nesmí ocitnout na cizí infrastruktuře: požadavky zákazníka, bankovní nebo zdravotnický sektor, státní systémy, práce s osobními údaji.

Zde je důležité chápat nuanci. Self-hosted runner sám o sobě okruh neuzavírá: pokud repozitář žije na GitHub.com, kód už tam stejně je. Vlastní runner řeší jinou úlohu — aby provádění probíhalo ve vašem perimetru: build s přístupem k interním balíčkovým repozitářům, testy proti databázi v privátní síti, deploy na servery, které nemají veřejnou adresu. Plně uzavřený okruh je už self-hosted git platforma (GitLab CE, Gitea, Forgejo) plus vlastní runnery.

Praktický bonus téže vlastnosti: runner uvnitř vaší sítě má přístup k produkčním serverům po privátních adresách, a nemusíte kvůli deploy otevírat SSH ven.

2.3 Specifické železo a prostředí

Standardní runnery platforem jsou univerzální Linux stroje střední výkonnosti. Pokud vaše úloha vychází z těchto mezí, vlastní runner je často jediná varianta:

• GPU pro trénování a testování modelů nebo pro build s CUDA.
• ARM pro nativní build pod ARM servery, Raspberry Pi nebo mobilní platformy. Emulace přes QEMU funguje, ale je několikanásobně pomalejší.
• Konkrétní verze OS: build balíčku pod CentOS 7 nebo testování na jádru, které ve standardních image není.
• Hodně RAM: build velkého monorepozitáře nebo integrační testy, které zvedají desítku služeb najednou.
• Rychlá lokální cache: NVMe s prohřátou cache závislostí a vrstev Dockeru dává zrychlení, které na čistém stroji pokaždé nebude.

2.4 Cena: výpočet místo pocitů

Porovnání má smysl jen na konkrétních číslech. Vezměme tým, který dělá 60 buildů denně po 10 minutách, tedy přibližně 13 000 minut měsíčně:

U malého projektu s několika buildy denně je obraz opačný: bezplatná kvóta stačí s rezervou a platit za VPS nemá smysl. Bod zvratu u většiny týmů nastává mezi 3 000 a 10 000 minutami měsíčně, podle platformy a podle toho, jak těžké jsou buildy.

A hned poctivé upozornění: „zdarma“ ve sloupci vlastního runneru se týká jen minut. Reálná cena je VPS plus čas inženýra na počáteční nastavení a další údržbu (aktualizace OS, čištění disku, aktualizace samotného agenta). U jednoho stroje je to několik hodin na startu a přibližně hodina měsíčně dál. Pokud je vaše úspora na minutách menší než tato hodina, zůstaňte na cloudových runnerech.

3. Jak je runner uspořádán

Runner vypadá složitěji, než je. Ve skutečnosti je to obyčejný procesu na pozadí (služba systemd nebo kontejner), který dělá ve smyčce jednu prostou věc: ptá se platformy, jestli pro něj je práce.

3.1 Model polling: runner si sám jde pro úlohy

Klíčová architektonická vlastnost: platforma se nikdy nepřipojuje k runneru. Všechno je naopak. Po registraci agent otevírá odchozí HTTPS spojení k platformě a drží ho, přičemž se periodicky ptá na další úlohu. GitLab Runner to dělá požadavkem na API s intervalem několika sekund, agent GitHubu drží dlouhé spojení a čeká na přidělení úlohy.

Z toho vyplývají tři praktické důsledky:

• Není potřeba veřejná IP a otevřené porty. Runner funguje za NAT, v domácí síti, za firemním firewallem.
• Není potřeba příchozí provoz vůbec. Pro firewall to znamená: příchozí spojení jsou zakázána úplně, kromě vašeho SSH pro administraci.
• Runner přežije výpadek spojení. Po obnovení sítě prostě pokračuje v dotazování, a platforma postaví úlohu do fronty a počká na volného agenta.

Registrace se provádí jednou tokenem, který vydává platforma. Dál má agent vlastní přihlašovací údaje a registrační token už nepoužívá. Token s právy registrace runneru je citlivý secret: s ním může cizí člověk připojit vlastní stroj k vašemu projektu a začít dostávat vaše úlohy spolu se secrets.

3.2 Co se děje uvnitř úlohy

Když platforma přiděluje úlohu, agent prochází jedním a týmž cyklem:

1. Získání popisu úlohy. Repozitář, commit, proměnné prostředí, seznam kroků a dočasný přístupový token, který platí jen po dobu trvání úlohy.
2. Příprava pracovního adresáře. Vytvoření nebo vyčištění workspace, zvednutí kontejneru (pokud je executor kontejnerový), připojení servisních kontejnerů typu databáze pro testy.
3. Checkout. Získání kódu s dočasným tokenem, obvykle mělké klonování kvůli rychlosti.
4. Provádění kroků. Příkazy se provádějí postupně, každý ve svém procesu. Nenulový návratový kód zastavuje úlohu, pokud krok není výslovně označen jako nepovinný.
5. Streamování logů. Výstup se přenáší na platformu po částech během provádění, proto je log vidět v reálném čase, a ne až po dokončení.
6. Artefakty a cache. Uvedené soubory se zabalí a nahrají do úložiště platformy, cache se uchová pro další spuštění.
7. Dokončení a úklid. Agent oznamuje status a uvolňuje se pro další úlohu.

3.3 Executory: kde přesně se příkazy provádějí

Executor je odpověď na otázku „v jakém prostředí agent spouští vaše příkazy“. Na volbě závisí jak pohodlí, tak úroveň izolace.

Shell. Příkazy se provádějí přímo na hostiteli, jménem uživatele, pod kterým agent běží. Nejjednodušší varianta: nic není třeba instalovat, všechno, co je na serveru, je v buildu dostupné. Mínusy jsou také přímé: žádná izolace mezi úlohami, společné prostředí, které se postupně znečišťuje, a plná závislost buildu na tom, co někdo nainstaloval na server minulý měsíc.

Docker. Každá úloha se provádí v čerstvém kontejneru z uvedeného image. To je standardní volba pro většinu týmů: prostředí je popsáno v konfigu pipeline, každá úloha startuje z čistého stavu, verze nástrojů jsou fixovány image.

# config.toml pro GitLab Runner s Docker executorem
concurrent = 4
check_interval = 3

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

Kubernetes. Každá úloha je samostatný pod v clusteru. Dává automatické škálování pod zátěží a přirozenou izolaci, ale má smysl jen tam, kde cluster už je a je ho komu spravovat.

V GitHub Actions terminologie executorů není: agent ve výchozím nastavení provádí kroky na hostiteli (obdoba shell), a kontejnerizace se zapíná na úrovni úlohy klíčem container:. Pro clustery existuje samostatná komponenta, která vytváří jednorázové runnery v Kubernetes.

4. Požadavky na infrastrukturu

4.1 Kolik zdrojů je reálně potřeba

Samotný agent nespotřebovává téměř nic: je to několik desítek megabajtů paměti ve stavu čekání. Zdroje nesežere on, ale vaše buildy, proto jsou požadavky určeny nejtěžší úlohou v pipeline.

Nejčastěji se podceňuje právě disk. Docker image, cache vrstev, stažené závislosti a artefakty rostou nenápadně, a první havárie na vlastním runneru je u většiny týmů ne nedostatek paměti, ale no space left on device uprostřed buildu. Počítejte s automatickým úklidem podle rozvrhu a s monitoringem volného místa od prvního dne.

Druhý nejčastější je nedostatek RAM u buildů frontendu: sestavení velkého JavaScript projektu snadno naráží na gigabajt až dva, a proces končí bez srozumitelné chyby, prostě zmizí. Pokud build padá nepředvídatelně a bez logů, nejdřív se podívejte, jestli ho nezabil mechanismus uvolňování paměti.

4.2 Síť: jen odchozí spojení

K práci runner potřebuje jen odchozí HTTPS k platformě a k těm zdrojům, odkud tahá závislosti: registry balíčků, registry image, zrcadla distribuce. Příchozí porty nejsou potřeba žádné.

Minimální rozumná konfigurace firewallu na serveru runneru:

# příchozí: jen SSH pro administraci, lépe ze známých adres
ufw default deny incoming
ufw default allow outgoing
ufw allow from 203.0.113.0/24 to any port 22 proto tcp
ufw enable

Samostatnou kapitolou je přístup runneru k produkci. Pokud runner provádí deploy, musí dosáhnout na cílové servery, a nejlepší varianta je privátní síť mezi nimi: deploy jde vnitřní adresou, veřejné SSH na produkčním serveru zůstává zavřené. Vynášet runner do téže sítě jako produkci stojí za to právě kvůli tomu, a ne kvůli pohodlí.

4.3 Jeden runner nebo několik

Jeden agent ve výchozím nastavení provádí jednu úlohu současně. Pokud jsou ve fázi tři paralelní kontroly, budou se provádět po řadě, a k žádnému zisku v čase nedojde.

Paralelismu se dosahuje dvěma způsoby. V GitLab Runneru může jeden proces obsluhovat několik úloh současně: parametr concurrent v config.toml zadává celkový počet. V GitHub Actions je jeden agent jedna úloha, proto se pro paralelní provádění spouští několik agentů, a to i na jednom stroji.

Praktické pravidlo: jedna paralelní úloha na každé 2 vCPU. Nastavovat concurrent = 8 na dvoujádrovém VPS nemá smysl, protože úlohy začnou soupeřit o procesor a každá se bude provádět déle, než kdyby šly po řadě.

Když je runnerů více než jeden, je užitečné hned je rozdělit podle určení přes tagy nebo štítky: samostatný runner pro buildy a testy, samostatný pro deploy na produkci. Není to jen o zdrojích, ale i o bezpečnosti: produkční secrets se pak dostávají jen na ten stroj, který skutečně dělá deploy.

5. Bezpečnost: hlavní principy

Self-hosted runner je stroj, který z definice provádí kód z repozitáře. Pokud má přístup k produkci a k secrets, automaticky se stává jedním z nejcennějších cílů ve vaší infrastruktuře. Čtyři pravidla níže zavírají většinu typických chyb.

5.1 Nepřipojujte vlastní runner k veřejným repozitářům

To je hlavní pravidlo a nemá výjimky pro začátečníky. Obě platformy přímo nedoporučují používat self-hosted runnery ve veřejných projektech, a důvod je fundamentální: jakýkoli cizí člověk může vytvořit fork vašeho repozitáře, změnit soubor pipeline a otevřít pull request. Pokud váš runner tuto úlohu vezme, provede cizí kód na vašem serveru.

Dál se scénář rozvíjí rychle: čtení souborů na disku, pokus dostat se k secrets v paměti procesu, skenování privátní sítě, do které je runner umístěn, uchycení přes cron nebo systemd jednotku. Pro veřejné repozitáře je správnou odpovědí cloudové runnery: tam se každá úloha provádí na jednorázovém stroji, kterého není škoda.

Pokud je vlastní runner pro veřejný projekt přece jen potřeba (například build pod ARM), povinné minimum jsou jednorázové (ephemeral) runnery, které se ničí po každé úloze, izolovaná síť bez přístupu k něčemu cennému a povinné ruční potvrzení spuštění pipeline pro pull requesty z externích forků.

5.2 Docker executor jako minimální úroveň izolace

Kontejner není plnohodnotný sandbox, ale je to mnohem lepší než provádění příkazů přímo na hostiteli. Minimální sada požadavků:

• Bez privileged. Privilegovaný kontejner jsou fakticky práva root na hostiteli.
• Bez připojování socketu Dockeru. Přístup k /var/run/docker.sock dovoluje úloze spustit kontejner s připojeným kořenovým oddílem hostitele.
• Omezení zdrojů. Limity CPU a paměti na kontejner, aby jedna úloha nepoložila celý server.
• Čerstvý stav. Každá úloha startuje z nového kontejneru, bez znovupoužití předchozího.

5.3 Samostatný systémový uživatel s minimálními právy

Agent nikdy nesmí běžet pod root. Vytvořte samostatného systémového uživatele, jehož jménem služba běží:

sudo useradd --system --create-home --shell /bin/bash ci-runner
# bez sudo, bez přístupu do cizích domovských adresářů
sudo chmod 750 /home/ci-runner

Dál podle seznamu: tento uživatel nemá práva sudo, pracovní adresář patří jen jemu, služba se spouští přes systemd jeho jménem, a SSH klíče pro deploy (pokud jsou tu potřeba) jsou vydány samostatnému omezenému uživateli na cílovém serveru, a ne rootu.

5.4 Secrets jen přes mechanismus platformy

V repozitáři nesmí být jediné heslo, token nebo klíč. Secrets se uchovávají v mechanismu platformy (Secrets v GitHubu, CI/CD Variables v GitLabu) a dostávají se do úlohy jako proměnné prostředí na dobu jejího provádění.

Několik pravidel, která stojí za to použít hned:

• Maskování v logech. Obě platformy umějí skrývat hodnoty secrets ve výstupu. Není to ochrana před záměrným vytažením, ale zachraňuje před náhodným echo.
• Vazba na chráněné větve. Produkční secrets jsou dostupné jen úlohám z chráněné větve nebo z definovaného prostředí, a ne jakékoli větvi jakéhokoli vývojáře.
• Minimální práva. Token pro deploy umí jen deployovat. SSH klíč je vázán na jednoho uživatele a v případě potřeby na jeden povolený příkaz.
• Rotace. Secrets se mění po odchodu člověka s přístupem a po jakémkoli podezřelém incidentu s runnerem.

6. Závěr

Self-hosted runner je architektonicky jednoduchá komponenta: agent se dotazuje platformy, dostává úlohu, provádí kroky ve zvoleném prostředí, odevzdává logy a artefakty. Celá složitost není v agentovi, ale v tom, co je kolem něj.

• Kdy přecházet. Když se kvóta minut vyčerpává každý měsíc, když se provádění má odehrávat uvnitř vašeho perimetru, když je potřeba železo, které standardní runnery nemají. Pro malý projekt s desítkou buildů denně jsou cloudové runnery levnější a jednodušší.
• Síť. Runner funguje na odchozích spojeních, proto nepotřebuje veřejnou IP a otevřené porty. Je to zároveň pohodlné i bezpečné.
• Zdroje. Začít lze s 1 vCPU a 1 GB RAM, reálné pracovní minimum pro buildy s Dockerem jsou 2 vCPU, 4 GB a 50 GB disku. Disk a úklid po úlohách jsou důležitější, než se na startu zdá.
• Bezpečnost. Žádné veřejné repozitáře bez izolace, Docker executor bez privileged, samostatný uživatel bez sudo, secrets jen přes platformu a jen pro chráněné větve.

Klíčový rozdíl od cloudového runneru zůstává jeden: tam každý build začíná z čistého listu, a u vás je čistotu nutné udržovat samostatně. To je právě ta cena, kterou platíte za kontrolu, předvídatelnou cenu a přístup do vlastní sítě.

Co dál v sérii

Architektura je u obou platforem společná, ale realizace znatelně odlišná: v GitHub Actions je to agent se štítky a kroky z marketplace, v GitLab CI je to gitlab-runner s tagy, executory a vlastním konfigem. Proto jsou další dvě části praktické a strukturou paralelní.

Ve třetí části stavíme vlastní runner pro GitHub Actions na VPS a skládáme první funkční pipeline: registrace agenta, služba systemd, struktura workflow, cache. Ve čtvrté totéž pro GitLab CI: gitlab-runner, executory, .gitlab-ci.yml, fáze a pravidla. Pátá část je o Gitea Actions, kdy git platforma a pipeline žijí na jednom vlastním serveru. Šestá shrnuje sérii porovnáním tří platforem a odpovědí na otázku, co volit pro konkrétní podmínky.

Časté otázky