gitea-ci-library/docs/runner.md

Gitea Actions — Runtime-ympäristö

Kuuluu arkkitehtuuriin: architecture.md. Asennusohjeet: README.md.

Tämä dokumentti kuvaa miten Gitea Actions runner suorittaa workflowt ja minkälaisen runtime-ympäristön se tarjoaa.

---

Runnerin rooli

Runner on pelkkä suoritin. Se ei sisällä build-työkaluja (Maven, npm, Docker) — ne tulevat workflow'n määrittelemistä konteista. Runner vastaanottaa työt Gitea-palvelimelta, ajaa ne ja raportoi tulokset takaisin.

Gitea → dispatch job → Runner → pull containers → execute steps → report status

Runnerilla on yksi vastuu: suorittaa workflow-steppejä. Kaikki runtime-ympäristön määrittely tapahtuu workflow-tiedostossa.

Kontit ja palvelut

Jokainen job voi määritellä käyttämänsä kontit. Tämä vastaa Jenkinsin pod template -konseptia, mutta on yksinkertaisempi:

container: — ajonaikainen ympäristö

Workflow-steppi ajetaan tässä kontissa. Eri jobeilla voi olla eri kontti:

jobs:
  build-java:
    runs-on: ubuntu-latest
    container: maven:3.9-eclipse-temurin-21
    steps:
      - run: mvn verify

  build-node:
    runs-on: ubuntu-latest
    container: node:22
    steps:
      - run: npm ci && npm test

services: — rinnakkaiset palvelut

Palvelukontit käynnistyvät jobin ajaksi ja ovat käytettävissä localhost-verkon kautta:

jobs:
  build-with-docker:
    runs-on: ubuntu-latest
    container: maven:3.9-eclipse-temurin-21
    services:
      docker:
        image: docker:dind
        env:
          DOCKER_TLS_CERTDIR: ""
    steps:
      - run: mvn package
      - run: docker build -t my-app .

Kontit vedetään ajonaikaisesti registrystä (Docker Hub, Gitea Packages, mikä tahansa). Runnerin ei tarvitse tietää niistä etukäteen.

Docker-in-Docker

Runner-podilla on kaksi tapaa käyttää Dockeria:

Tapa	Kuvaus	Sopii
DinD (docker:dind)	Oma Docker daemon service-kontissa	Suositeltu K8s-ympäristöön
Docker socket	Jaettu /var/run/docker.sock	Yksinkertainen, vähemmän eristetty

Gitea act runnerin Helm chart tukee DinD:tä oletuksena.

Label-järjestelmä

Runnerit rekisteröidään labelilla. Workflow valitsee runnerin runs-on-kentällä:

jobs:
  build:
    runs-on: ubuntu-latest    # ← label

Labelit asetetaan runnerin rekisteröinnissä:

# Helm
--set runner.labels="ubuntu-latest,docker,arm64"

# Binääri
./act_runner register --labels ubuntu-latest,docker

Eri labelit mahdollistavat erikoistuneet runnerit (ARM, GPU, Windows), mutta MVP:ssä riittää yksi ubuntu-latest.

Runner-tasot

Taso	Scope	Riski	Käyttötapaus
Global	Kaikki organisaatiot ja repot	Token-vuoto → hyökkääjä voi ajaa koodia missä tahansa	Jaettu infra, keskitetty hallinta
Organization	Yhden organisaation repot	Rajoittuu yhteen orgiin	Per organisaatio, eristetty — suositeltu

Jenkins-vertailu

Jenkins	Gitea Actions
Pod template (YAML) määrittelee kontit	container: + services: per job
Jokaiselle jobille oma pod	Jokaiselle jobille omat konttimääritykset
DinD sidecar-podissa	services: docker:dind samassa jobissa
Agentti = erillinen JVM-prosessi	Runner = kevyt Go-binääri tai K8s-pod
Labelit Jenkins-nodessa	Labelit runner-rekisteröinnissä