Proxmox GitHub Actions Homelab

CI w homelabie, który niczego nie wystawia

Limity GitHub Actions kończyły mi się w połowie miesiąca, a serwer w domu stał bezczynny. Spawnpool daje każdemu jobowi świeży kontener LXC na Proxmoksie i nie otwiera na zewnątrz ani jednego portu.

AK Aleksander Kowalski
• 29 October 2026 • 8 min

Znowu ten sam mail od GitHuba: wykorzystałeś limit minut GitHub Actions. Połowa miesiąca, kilka prywatnych repozytoriów, testy Androida, lint, deploy stron. W tym samym czasie w szafce stoi serwer Proxmox, który przez większość dnia nic nie robi. Wolne zasoby leżą metr od biurka, a ja czekam na nowy miesiąc rozliczeniowy.

Odpowiedź wydaje się oczywista: postaw własny runner. Tylko że runner to maszyna, która wykonuje cudzy kod wewnątrz mojej sieci domowej. Nawet jeśli repo są moje, to zależności, które ściągają, już nie. Dlatego zanim napisałem pierwszą linijkę, ustaliłem jeden warunek: narzędzie nie może niczego wystawić na zewnątrz.

TL;DR

Aspekt Pomysł
Problem limity minut CI w prywatnych repozytoriach
Zasoby wolny CPU i RAM w homelabie (Proxmox)
Jednostka pracy jeden job = jeden świeży kontener LXC, kasowany po jobie
Ruch sieciowy tylko połączenia wychodzące, zero portów otwartych na internet
Uprawnienia jedna GitHub App zainstalowana tylko na wybranych repo
Poświadczenia jednorazowy token na jeden job, nic stałego na runnerze
Pojemność jeden wspólny limit dla wszystkich repo, kolejka FIFO

Narzędzie nazywa się Spawnpool. To jeden proces w sieci domowej (dalej: kontroler), który pyta GitHuba o joby i zarządza kontenerami na Proxmoksie. W tym tekście opisuję samą ideę i przepływ, bez kodu.

Dlaczego nie zwykły runner

Stały runner, zarejestrowany raz i działający miesiącami, ma dwie wady. Pierwszą poznałem na własnej skórze.

Pierwsza to stan, który przechodzi z joba na job. Po kilku tygodniach osierocone wolumeny Dockera zjadły mi wszystkie inody na dysku runnera. Dysk pokazywał 32% zajętości, a Docker nie potrafił utworzyć pliku. Każdy job zostawia coś po sobie i kolejny job dziedziczy ten bałagan.

Druga to długożyjące poświadczenie. Stały runner trzyma na dysku swoje poświadczenia, czyli klucz, którym loguje się do GitHuba. Job albo zależność, którą job instaluje, może zrobić coś złośliwego. Wtedy te poświadczenia i cała maszyna zostają do jego dyspozycji także po zakończeniu joba.

Autoskalery rozwiązują pierwszy problem, ale część z nich wprowadza trzeci. Opierają się na webhookach GitHuba, więc potrzebują publicznego adresu albo tunelu. A tego właśnie nie chciałem.

Trzy zasady

Jeden job, jeden kontener

Każdy job dostaje świeży kontener LXC sklonowany ze wzorca. Wzorzec to przygotowany zawczasu obraz z runnerem i Dockerem. Kontener wykonuje dokładnie jeden job, wyłącza się i jest kasowany. Nie ma czego sprzątać, bo nie ma czego przenosić.

Dlaczego LXC, a nie maszyna wirtualna? Klon kontenera powstaje w kilka sekund i jest lżejszy od VM: nie ma osobnego jądra ani bootu systemu. Cena jest taka, że kontener dzieli jądro z hostem. To świadomy kompromis: LXC tylko dla moich prywatnych repozytoriów. Gdybym miał wpuścić kod obcych ludzi, na przykład z PR-ów do publicznego repo, każdy job dostałby pełną maszynę wirtualną.

Nic nie czeka na połączenia z internetu

To serce całego pomysłu. Spawnpool sam łączy się z GitHubem i pyta, czy w kolejce czekają joby. Używa do tego long-pollingu, czyli zapytania, które wisi otwarte, dopóki GitHub nie ma czegoś do przekazania. Nie ma webhooków ani publicznego adresu. Spawnpool nie potrzebuje żadnego przekierowania portu na routerze.

Runner w kontenerze działa tak samo: sam łączy się z GitHubem, pobiera job i odsyła wyniki. Każde połączenie, które przekracza granicę sieci domowej, jest zainicjowane z domu.

Kontenery z jobami siedzą w osobnej, izolowanej sieci, która ma dostęp tylko do internetu. Jedyna dziura w tej izolacji prowadzi do kontrolera, po jednorazowy token. Kontroler rozpoznaje kontener po adresie, a firewall Proxmoxa (filtr IP i MAC) nie pozwala kontenerowi podszyć się pod cudzy adres. Token działa dla jednego joba. Kiedy runner go zużyje albo minie czas, token przestaje istnieć.

Jeden wspólny limit i uczciwa kolejka

Serwer ma jedną pulę RAM-u, a repozytoriów jest osiem. Każde repo może mieć własny limit równoległych jobów, ale ponad nimi stoi jeden globalny limit: łącznie w homelabie nigdy nie działa więcej kontenerów. Repo może chcieć pięciu kontenerów naraz, ale jeśli limit globalny wynosi trzy, to w całym homelabie działają najwyżej trzy.

Kiedy miejsca brakuje, joby czekają w kolejce FIFO. Kto pierwszy przyszedł, ten pierwszy dostaje kontener, bez priorytetów. Job z repo, które wyczerpało własny limit, czeka, ale nie traci miejsca w kolejce. Limit nie jest licznikiem, który może się rozjechać: każde miejsce to rezerwacja konkretnego kontenera. Miejsce zwalnia się dopiero wtedy, gdy Proxmox potwierdzi, że kontener zniknął.

Uprawnienia z jednego miejsca: GitHub App

Osiem repozytoriów to osiem miejsc, w których trzeba by rejestrować runnery, trzymać tokeny i pamiętać o ich rotacji. Zamiast tego wszystkie uprawnienia mają jedno źródło: jedną GitHub App zainstalowaną tylko na wybranych repozytoriach.

Kontroler działa jako ta aplikacja. Kluczem prywatnym podpisuje krótko żyjący JWT i dostaje od GitHuba token instalacji ważny godzinę. Tym tokenem zakłada w każdym repo scale set, czyli grupę runnerów, do której trafiają joby z runs-on: spawnpool. Na jego podstawie pyta o joby i dla każdego kontenera prosi o konfigurację JIT (just-in-time), ważną dla jednego joba. Kontroler nie używa osobistych tokenów (PAT) ani tokenów rejestracyjnych dla każdego repo osobno, a kontenery nigdy nie widzą klucza aplikacji.

Aplikacja dostaje tylko trzy uprawnienia. Administracja repozytorium jest potrzebna, bo bez niej nie da się zarządzać runnerami. Metadane to minimum każdej aplikacji. Odczyt Actions służy tylko do tego, żeby wiedzieć, ile job czekał w kolejce. Webhook jest wyłączony, bo aplikacja niczego nie odbiera.

Dodanie repozytorium do puli to jedna linia na liście w konfiguracji. Automatyzacja uruchamiana z mojego komputera, moim kontem, daje aplikacji dostęp do repo, a potem zakłada w nim scale set. Aplikacja nie może sama dodać się do repozytorium, więc tego kroku nie robi kontroler. Usunięcie linii działa symetrycznie: scale set znika, a aplikacja traci dostęp do repo. Jedna lista mówi więc, które repo korzystają z domowego CI, i nie ma drugiego miejsca, które mogłoby się z nią rozjechać.

Jak to działa

<title id="spawnpool-diagram-title">Przepływ joba w Spawnpoolu</title> Kontroler w sieci domowej pyta GitHuba o joby, klonuje kontener ze wzorca na Proxmoksie, kontener pobiera od kontrolera jednorazowy token, rejestruje się w GitHubie, wykonuje jeden job i znika. Wszystkie połączenia przez granicę sieci domowej są wychodzące. GitHub Actions GitHub App na wybranych repo · joby z runs-on: spawnpool czekają w kolejce SIEĆ DOMOWA Kontroler kolejka FIFO wspólny limit kontenerów Proxmox Wzorzec runner + Docker Kontener job A Kontener job B wolne miejsce sieć izolowana: tylko internet 5. po jobie kontener wyłącza się i znika 1. pyta o joby połączenie wychodzące 2. klonuje 3. pobiera token jednorazowy 4. rejestruje się i wykonuje jeden job Zielone strzałki przekraczają granicę sieci i wszystkie wychodzą z domu. Z internetu nic nie wchodzi.
Przepływ jednego joba. Każdy kontener przechodzi kroki 3–5, a kontroler nie przyjmuje żadnych połączeń z internetu.

Krok po kroku:

  1. Kontroler pyta GitHuba o joby. Działa jako GitHub App i dla każdego repozytorium utrzymuje otwarte zapytanie. GitHub odpowiada, kiedy pojawi się job z runs-on: spawnpool. Kontroler sprawdza limit i ustawia job w kolejce.
  2. Kontroler klonuje wzorzec. Kiedy w limicie jest wolne miejsce, prosi Proxmoxa o nowy kontener ze wzorca i go uruchamia.
  3. Kontener pobiera jednorazowy token. Po starcie kontener pyta kontroler o swoją konfigurację. Kontroler wcześniej pobrał ją z GitHuba jako aplikacja. Kontener dostaje token ważny dla jednego joba. Token trafia tylko do pamięci (tmpfs), plik znika tuż przed startem runnera, a sam token po użyciu przestaje działać.
  4. Runner rejestruje się w GitHubie i wykonuje job. To znowu połączenie wychodzące. Większość jobów biegnie w obrazach Dockera, więc we wzorcu jest tylko to, czego nie da się tak uruchomić.
  5. Kontener znika. Po jobie runner się wyłącza, a kontroler kasuje kontener i zwalnia miejsce w limicie. Miejsce dostaje najstarszy czekający job.

Kontroler nie ma bazy danych. Po restarcie odtwarza stan z dwóch źródeł prawdy: z Proxmoxa (jakie kontenery istnieją) i z GitHuba (jakie joby czekają). Działające kontenery oznaczone swoim tagiem przejmuje i prowadzi dalej. Gościa w swojej puli bez tego tagu, czyli resztkę przerwanego klonowania, traktuje jak sierotę i kasuje.

Inspiracje

Nie ja pierwszy wpadłem na pomysł efemerycznych runnerów na Proxmoksie. Kilka projektów, które warto znać:

Wady?

Żeby było uczciwie:

  • LXC dzieli jądro z hostem. Ucieczka z kontenera to dostęp do hosta Proxmoxa, a izolacja sieci tego nie zatrzyma. Dlatego ten model ma sens tylko dla własnych prywatnych repozytoriów.
  • Klucz aplikacji to najcenniejszy sekret. Daje prawo administracji na wszystkich repo w puli, więc leży tylko na kontrolerze i w menedżerze haseł, nigdy w kontenerze.
  • Każdy job zaczyna od zera. Klon, start i rejestracja kosztują czas, którego stały runner nie traci. Nie ma też cache'u między jobami, więc ciężkie narzędzia (u mnie JDK i Android SDK) trzeba trzymać we wzorcu.
  • Domowe łącze to wąskie gardło. Wysyłanie dużych obrazów Dockera przez domowy upload trwa wieki. Buildy obrazów z pushem zostawiłem na runnerach GitHuba, a w domu biegną testy, lint i deploye.
  • To kolejny kawałek infrastruktury do utrzymania. Wzorzec trzeba przebudować przy każdej nowej wersji runnera, bo GitHub przestaje dawać joby runnerom, które nie zaktualizowały się w ciągu 30 dni od wydania. Limit globalny trzeba dobrać do pamięci serwera, bo tylko on chroni serwer przed swapowaniem.

Podsumowanie

Pomysł mieści się w jednym zdaniu: jeden job dostaje jeden świeży kontener, a każde połączenie wychodzi z domu, nigdy do niego nie wchodzi. Reszta to konsekwencje. Wspólny limit pilnuje pamięci serwera, kolejka FIFO pilnuje kolejności, jednorazowy token sprawia, że po jobie nie zostaje nic, co dałoby się ukraść, a jedna GitHub App trzyma wszystkie uprawnienia w jednym miejscu.

Limity minut przestały być moim problemem, a serwer w szafce wreszcie zarabia na swój prąd.


Masz pytania? Napisz na LinkedIn.

Podobał Ci się artykuł?

Nowe wpisy raz w miesiącu. Zero spamu.