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
Krok po kroku:
- 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. - Kontroler klonuje wzorzec. Kiedy w limicie jest wolne miejsce, prosi Proxmoxa o nowy kontener ze wzorca i go uruchamia.
- 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ć.
- 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ć.
- 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ć:
- actions/actions-runner-controller: oficjalny autoskaler GitHuba, punkt odniesienia dla całej kategorii, ale wymaga Kubernetesa.
- actions/scaleset: klient Go do API runner scale setów. To ten mechanizm pozwala pytać GitHuba o joby bez webhooków.
- JeffResc/actions-runner-scaleset-proxmox: ten sam pomysł na maszynach wirtualnych, z pulą gorących i ciepłych VM, żeby skrócić start joba.
- klponce/proxmox-actions-runners: kontroler w stylu ARC, gdzie każdy job dostaje własną VM zamiast poda.
- Shhinobi/proxmox-jit-runners: orkiestrator runnerów w kontenerach LXC z jednorazową konfiguracją JIT, ale oparty na webhookach.
- cocardoso/gh-runners-manager: efemeryczne runnery w LXC przez API scale setów, tylko z połączeniami wychodzącymi i z interfejsem webowym. Najbliższy mojemu podejściu.
- LukasK32/fleeting-plugin-proxmox: odpowiednik dla GitLaba, wtyczka do autoskalera GitLab Runnera na Proxmoksie.
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.