Rularea unui runner GitHub Actions propriu pe un VPS

Runnerele găzduite de GitHub sunt o alegere implicită bună. Nu mai ai nevoie de ele în clipa în care un build vrea ceva ce ele nu au — registrul tău privat de pachete, o anumită versiune de unelte pe care te-ai săturat s-o reinstalezi la fiecare rulare, o bază de date din propria rețea sau pur și simplu mai mult control asupra mașinii. Atunci un runner propriu pe un VPS își merită locul.

Ghidul ăsta pune unul în funcțiune cum trebuie: instalat, înregistrat, ținut în viață sub systemd și — partea pe care oamenii o greșesc — sigur. Hai să începem cu ea, pentru că ea e cea care mușcă.

Singura regulă de securitate

Un workflow GitHub Actions rulează cod arbitrar — orice e în fișierul workflow-ului și orice aduce după el codul acela. Pe propriul repo, e codul tău, și e în regulă. Pe un repo public, un pull request de la un necunoscut își poate rula codul lui pe runnerul tău. Nu e un bug; așa funcționează CI-ul. Propria documentație GitHub spune direct: nu folosi runnere proprii cu repository-uri publice.

Deci regula e simplă și nenegociabilă: runnerele proprii sunt pentru repo-uri private. Dacă repo-ul tău e public, folosește runnere găzduite de GitHub și mergi mai departe. Tot ce urmează presupune un repo privat.

De ce are nevoie un runner de la mașină

Depinde de build, iar tu ar trebui să dimensionezi după al tău, nu după un număr de pe o pagină:

• O sarcină obișnuită de compilare și testare — 2 nuclee și 4-8 GB sunt comode. Small ($8, 4 vCPU / 4 GB) sau Medium ($12, 6 vCPU / 6 GB) acoperă majoritatea.
• Builduri mai grele — compilări native mari, builduri de imagini Docker mari, suite de teste flămânde de memorie — vor mai multă rezervă. Urmărește o rulare reală (htop cât rulează buildul) și dimensionează după ce vezi efectiv, nu după speranță.

Contează și discul: cache-urile de build, straturile Docker și repo-urile clonate se adună. Fii atent la el și curăță.

1. Pregătește mașina

Creează un utilizator non-root pentru runner — instalatorul GitHub refuză oricum să ruleze ca root, și așa și vrei:

sudo adduser --disabled-password --gecos "" runner
sudo usermod -aG sudo runner   # only if your builds genuinely need sudo

Instalează tot ce-ți trebuie pentru builduri — unelte pentru limbaj, Docker, unelte de build. De exemplu, dacă sarcinile tale construiesc containere:

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

2. Descarcă și înregistrează runnerul

În repo-ul (sau organizația) tău de pe GitHub, mergi la Settings → Actions → Runners → New self-hosted runner. GitHub îți dă exact comenzile de descărcare și un token de înregistrare (e de scurtă durată — ia-l proaspăt). Ca utilizatorul runner:

sudo -iu runner
mkdir actions-runner && cd actions-runner
# use the exact URL GitHub shows you for your 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 îți cere un nume de runner, etichete și un folder de lucru — valorile implicite sunt în regulă la început. Etichetele sunt felul în care workflow-ul tău vizează acest runner (runs-on: self-hosted).

3. Rulează-l ca serviciu systemd

Runnerul vine cu un script ajutător care îți instalează un serviciu systemd — folosește-l, ca runnerul să supraviețuiască repornirilor și să repornească după erori. Instalarea rămâne a utilizatorului runner, dar comenzile de serviciu au nevoie de root:

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

Asta înregistrează actions.runner.* ca unitate systemd care rulează ca utilizatorul runner și pornește la boot. Logurile ajung în journald:

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

Înapoi pe pagina Runners din GitHub, runnerul tău apare acum ca Idle — punct verde. Îndreaptă un workflow spre el:

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

Faci push, iar sarcina rulează pe mașina ta.

4. Ține-l curat

Un runner propriu își refolosește sistemul de fișiere între sarcini — ăsta e câștigul de viteză (cache-uri calde) și capcana (starea rămasă). Două obiceiuri îl țin sănătos:

• Curăță regulat. Mai ales Docker — docker system prune pe un cron, altfel discul se umple pe tăcute cu straturi moarte.
• Nu stoca secrete pe mașină. Folosește secretele GitHub Actions, injectate la fiecare rulare, nu fișiere care stau în directorul home al runnerului. Dacă runnerul e compromis, tot ce e pe disc pleacă odată cu el.

Dacă ai nevoie de un mediu cu adevărat curat pentru fiecare sarcină, rulează fiecare sarcină într-un pas de container — runnerul rămâne, dezordinea sarcinii nu.

Când să găzduiești singur, cinstit

Găzduiește singur când ai nevoie de propriile unelte deja instalate, de acces la resurse din rețeaua privată sau de control asupra mașinii. Rămâi la runnerele găzduite de GitHub când un mediu curat, de unică folosință, și minutele lor ți se potrivesc — chiar e mai simplu, iar simplitatea valorează ceva. Și niciodată, pe un repo public, nu găzdui singur. Asta nu e o preferință.

Dacă ai nevoie de un runner pentru un repo privat: alege un plan — Small ($8) pentru builduri mai ușoare, Medium ($12) când devin mai grele —, plătește în USDC sau USDT (fără KYC, fără documente) și vei avea root în aproximativ 60 de secunde. Apoi parcurge pagina asta și vei avea un runner care preia sarcini câteva minute mai târziu.

Vezi planul și comandă un VPS →