docs(runner): add runtime environment documentation and fix Helm guide

Fix chart values (enabled, giteaRootURL, existingSecret), add log level config, and document runner architecture: containers, services, DinD, labels, and Jenkins comparison.
2026-06-08 11:21:05 +03:00
parent 234c217fea
commit 906e3f6061
3 changed files with 146 additions and 9 deletions
@@ -0,0 +1,111 @@
+# Gitea Actions — Runtime-ympäristö
+
+> Kuuluu arkkitehtuuriin: [architecture.md](architecture.md). Asennusohjeet: [README.md](../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:
+
+```yaml
+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:
+
+```yaml
+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ä:
+
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest    # ← label
+```
+
+Labelit asetetaan runnerin rekisteröinnissä:
+
+```bash
+# 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ä |