Uruchamianie samodzielnego runnera GitHub Actions na VPS

Runnery hostowane przez GitHub to dobry domyślny wybór. Przestajesz ich potrzebować w chwili, gdy build chce czegoś, czego nie mają — Twojego prywatnego rejestru pakietów, konkretnej wersji toolchainu, której masz dość reinstalowania przy każdym przebiegu, bazy danych w Twojej własnej sieci lub po prostu większej kontroli nad maszyną. Wtedy samodzielny runner na VPS zarabia na siebie.

Ten przewodnik uruchamia jeden porządnie: zainstalowany, zarejestrowany, żywy pod systemd i — część, którą ludzie mylą — bezpieczny. Zacznijmy od tej ostatniej, bo to część, która gryzie.

Jedna zasada bezpieczeństwa

Przepływ pracy GitHub Actions uruchamia dowolny kod — to, co jest w pliku przepływu, i to, co ten kod wciąga. Na Twoim własnym repozytorium to Twój kod, i jest w porządku. Na publicznym repozytorium pull request od obcego może uruchomić jego kod na Twoim runnerze. To nie błąd; tak działa CI. Własna dokumentacja GitHuba mówi wprost: nie używaj samodzielnych runnerów z publicznymi repozytoriami.

Więc zasada jest prosta i nienegocjowalna: samodzielne runnery są dla prywatnych repozytoriów. Jeśli Twoje repozytorium jest publiczne, użyj runnerów hostowanych przez GitHub i idź dalej. Wszystko poniżej zakłada prywatne repozytorium.

Czego runner potrzebuje od maszyny

Zależy od builda, i powinieneś dobrać rozmiar pod swój, a nie liczbę ze strony:

• Typowe zadanie kompiluj-i-testuj — 2 rdzenie i 4–8 GB jest wygodne. Small (8 $, 4 vCPU / 4 GB) lub Medium (12 $, 6 vCPU / 6 GB) obejmuje większość z nich.
• Cięższe buildy — duże natywne kompilacje, duże buildy obrazów Docker, pamięciożerne zestawy testów — chcą więcej zapasu. Obserwuj jeden prawdziwy przebieg (htop, gdy się buduje) i dobierz rozmiar pod to, co faktycznie widzisz, nie pod nadzieję.

Dysk też ma znaczenie: cache buildów, warstwy Docker i sklonowane repozytoria się sumują. Miej na to oko i usuwaj.

1. Przygotuj maszynę

Utwórz użytkownika innego niż root dla runnera — instalator GitHuba i tak odmawia uruchomienia jako root, i chcesz tego:

sudo adduser --disabled-password --gecos "" runner
sudo usermod -aG sudo runner   # tylko jeśli Twoje buildy naprawdę potrzebują sudo

Zainstaluj, czego potrzebują Twoje buildy — toolchain języka, Docker, narzędzia builda. Na przykład, jeśli Twoje zadania budują kontenery:

sudo apt update && sudo apt install -y docker.io
sudo usermod -aG docker runner

2. Pobierz i zarejestruj runner

W swoim repozytorium (lub org) na GitHubie idź do Settings → Actions → Runners → New self-hosted runner. GitHub daje Ci dokładne polecenia pobierania i token rejestracji (jest krótkotrwały — chwyć świeży). Jako użytkownik runner:

sudo -iu runner
mkdir actions-runner && cd actions-runner
# użyj dokładnego URL, który GitHub pokazuje dla Twojego OS/arch:
curl -o actions-runner-linux-x64.tar.gz -L "URL_FROM_GITHUB"
tar xzf actions-runner-linux-x64.tar.gz
./config.sh --url https://github.com/YOUR_ORG/YOUR_REPO --token YOUR_TOKEN

config.sh pyta o nazwę runnera, etykiety i folder roboczy — domyślne są w porządku na start. Etykiety to sposób, w jaki Twój przepływ celuje w tego runnera (runs-on: self-hosted).

3. Uruchom go jako usługę systemd

Runner dostarcza pomocnika, który instaluje usługę systemd za Ciebie — użyj go, by runner przetrwał restarty i restartował się przy awarii. Wciąż jako instalacja użytkownika runner, ale polecenia usługi potrzebują root:

sudo ./svc.sh install runner
sudo ./svc.sh start
sudo ./svc.sh status

To rejestruje actions.runner.* jako jednostkę systemd działającą jako użytkownik runner, startującą przy rozruchu. Logi idą do journald:

sudo journalctl -u 'actions.runner.*' -f

Z powrotem na stronie Runners GitHuba Twój runner pokazuje teraz Idle — zielona kropka. Skieruj na niego przepływ pracy:

jobs:
  build:
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v4
      - run: make test

Wypchnij, a zadanie działa na Twojej maszynie.

4. Utrzymuj go w czystości

Samodzielny runner ponownie używa swojego systemu plików między zadaniami — to wygrana szybkości (ciepłe cache) i footgun (pozostały stan). Dwa nawyki utrzymują go zdrowym:

• Usuwaj regularnie. Docker szczególnie — docker system prune na cronie, inaczej dysk po cichu wypełnia się martwymi warstwami.
• Nie przechowuj sekretów na maszynie. Użyj sekretów GitHub Actions, wstrzykiwanych na przebieg, nie plików leżących w domu runnera. Jeśli runner zostanie skompromitowany, wszystko na dysku idzie z nim.

Jeśli potrzebujesz naprawdę czystego środowiska na zadanie, uruchamiaj każde zadanie wewnątrz kroku kontenerowego — runner zostaje, bałagan zadania nie.

Kiedy hostować samodzielnie, uczciwie

Hostuj samodzielnie, gdy potrzebujesz własnego toolchainu wbudowanego, dostępu do prywatnych zasobów sieciowych lub kontroli nad maszyną. Zostań na runnerach hostowanych przez GitHub, gdy czyste, jednorazowe środowisko i ich minuty Ci pasują — to naprawdę prostsze, a prostsze jest coś warte. I nigdy, na publicznym repozytorium, nie hostuj samodzielnie. Ta jedna nie jest preferencją.

Jeśli runner na prywatnym repozytorium to, czego potrzebujesz: wybierz plan — Small (8 $) dla lżejszych buildów, Medium (12 $), gdy stają się cięższe — płać w USDC lub USDT (bez KYC, bez dokumentów), a będziesz miał root w około 60 sekund. Potem przejdź po tej stronie, a będziesz miał runnera podchwytującego zadania kilka minut później.