chemenu/kb/entities/tools/Act Runner.md

type, entity_type, tags, created, modified, related, sources, provenance, summary

type	entity_type	tags	created	modified	related	sources	provenance	summary
types/entity.md	tool	ci-cd gitea docker runner	2026-07-25	2026-09-01	uses Gitea hosts Gitea Actions	Source - Conversation - Versioning CI-CD and Content Migration Session 2026-08-30	sourced	Offizieller Gitea-Actions-Runner, der CI/CD-Workflows in Docker-Containern auf einer dedizierten Runner-VM ausführt; JavaScript-Actions brauchen node im Job-Container

Act Runner

Typ: Tool (Gitea Actions Runner)

Beschreibung

act_runner ist die offizielle Runner-Implementierung für Gitea Actions. Sie führt CI/CD-Workflows auf der VM ci-runner.example.net aus und läuft als Docker-Container im Host-Network-Modus, damit die Verbindung zu den Job-Containern und zum Actions Cache Server funktioniert.

Kerndaten

• Zweck: Ausführen von Gitea-Actions-Workflows
• Status: Aktiv (Stand 2026-07-12)
• Container-Image: gitea/act_runner:latest
• Containername: act_runner
• Restart Policy: unless-stopped
• Network Mode: host (entscheidend für die Cache-Anbindung)

Architektur

Container-Konfiguration

services:
  act_runner:
    image: gitea/act_runner:latest
    container_name: act_runner
    restart: unless-stopped
    network_mode: host
    environment:
      - CONFIG_FILE=/config.yaml
      - GITEA_INSTANCE_URL=http://192.0.2.10:3000
      - GITEA_RUNNER_REGISTRATION_TOKEN=${GITEA_RUNNER_REGISTRATION_TOKEN}
      - GITEA_RUNNER_NAME=ci-vm-runner
    volumes:
      - ./data:/data
      - ./config.yaml:/config.yaml:ro
      - /var/run/docker.sock:/var/run/docker.sock

Wesentliche Konfigurationseinstellungen

config.yaml:

cache:
  enabled: true
  host: "192.0.2.10"  # static IP of ci-runner.example.net
  port: 8088

container:
  network: ""  # empty = each job gets isolated bridge network

Routing-Labels

Eigene semantische Labels anstelle der Standard-Ubuntu-Labels:

• linux-docker
• container-builder
• k3s-deploy

Damit lassen sich Workflows gezielt an Runner mit bestimmten Capabilities leiten.

Beziehungen

• Teil von: Ökosystem Gitea Actions
• Verbindet sich mit: Gitea-Instanz unter docker-host.example.net für die Container-Ausführung
• Verwaltet: Job-Container mit isolierten Bridge-Netzen

Netzwerk

Host-Network-Modus

Die entscheidende Einstellung, die das Problem mit dem Actions Cache Server gelöst hat:

• Der Runner-Container nutzt network_mode: host
• Dadurch erreichen Job-Container den Cache-Server unter der konfigurierten statischen IP
• Die Cache-URL wird automatisch als Umgebungsvariable ACTIONS_CACHE_URL gesetzt
• Wichtig: network_mode: host und ein networks:-Block schließen sich in Docker Compose gegenseitig aus

Isolation der Job-Container

Obwohl der Runner im Host-Netz läuft:

• Jeder CI-Job läuft in einem eigenen, temporären Bridge-Netz
• container.network: "" in der config.yaml stellt das sicher
• Die Job-Isolation bleibt erhalten
• Nur der Runner-Prozess selbst hat Zugriff auf das Host-Netz

Verwaltung von Secrets

1Password-Anbindung

• Das Service-Account-Token wird über eine systemd-EnvironmentFile eingespielt (/etc/act_runner/secrets.env)
• Es ist das einzige Secret, das als Umgebungsvariable vorliegt
• In Gitea heißt das ein "Actions Secret"
• Workflows holen weitere Secrets zur Laufzeit über 1password/load-secrets-action@v2

Gitea-Token

• Workflows können ${{ gitea.token }} zur Authentifizierung verwenden
• Genutzt für Image-Pushes in die Gitea Container Registry
• Erfordert permissions: packages: write im Workflow
• Reicht auch für Releases, Tags und Asset-Uploads; ein Actions-Secret mit write:repository ist dafür nicht nötig. Belegt dadurch, dass ein Release-Workflow beim Versionssprung von selbst feuerte und Tarball samt .sha256 ablegte¹

Betrieb

Neustartverhalten

• Nach Netzwerkänderungen ist ein vollständiges docker compose down && docker compose up -d nötig
• Ein einfaches docker restart übernimmt Änderungen an network_mode nicht zuverlässig

Persistenz

• Workflow-Daten liegen im Volume ./data
• Konfiguration in ./config.yaml (nur lesend eingebunden)
• Docker-Socket eingebunden für den Zugriff auf BuildKit

JavaScript-Actions brauchen node im Job-Container

Nennt ein Job sein eigenes container:-Image, führt act_runner JavaScript-Actions - darunter actions/checkout - mit node innerhalb dieses Job-Containers aus. Ein schlankes Image bringt keins mit, und der Lauf endet vor dem ersten eigenen Schritt¹ :

OCI runtime exec failed: exec: "node": executable file not found in $PATH
  ❌  Failure - Main actions/checkout@v4
exitcode '127': command not found

Der erste Schritt eines solchen Jobs muss deshalb nodejs nachinstallieren, vor dem Checkout¹ :

- name: Install CI Dependencies
  run: apt-get install -y --no-install-recommends git nodejs curl unzip ca-certificates build-essential
- name: Checkout Code
  uses: actions/checkout@v7

Bekannt funktionierende Kombination auf dieser Installation, nicht neu herzuleiten¹ :

• actions/checkout@v7 und actions/upload-artifact@v3 (v4 ist auf dieser Instanz eingeschränkt)
• debian:trixie-slim als Job-Image; es trägt python3 3.13
• Die Labels linux-docker und container-builder nehmen beide einen Job an, der sein eigenes Image benennt

Ein gepinntes Image war ursprünglich als Vorsichtsmaßnahme gegen die undokumentierte Zuordnung von linux-docker zu einem Image gewählt worden. Die Vorsichtsmaßnahme verursachte den Fehlschlag: Das Label routete von Anfang an korrekt und startete den Container, nur fehlte im gewählten Image node¹ .

Läufe sind von außen nicht beobachtbar

Bei einem privaten Repository antwortet Gitea einem anonymen Aufrufer mit einem identischen 404 für ein unsichtbares und für ein nicht existierendes Repository¹ . Aus einem curl gegen die API lässt sich damit kein Rückschluss auf den Lauf-Zustand ziehen. Läufe und ihre Logs werden über den Gitea MCP Server gelesen.

Erprobte CI/CD-Szenarien

Der Runner deckt drei Szenarien nachweislich ab:

1. Arch-Paketbau - Builder-Benutzer ohne Root-Rechte, actions/upload-artifact@v3
2. Container-Builds - Debian-basierte Images, entferntes BuildKit
3. K3s-Deployments - Kubeconfig aus 1Password, kubectl-Operationen

Historie

• [2026-07-12] - Network Mode auf host umgestellt, um die Anbindung an den Actions Cache Server zu reparieren (ETIMEDOUT auf 172.18.0.2:39329)
• [2026-07-25] - Entity-Seite aus dem Quellen-Ingest erstellt
• [2026-08-30] - Ursache der bis dahin unerklärten Workflow-Fehlschläge geklärt: fehlendes node im gepinnten Job-Image, nicht ein falsches Runner-Label. nodejs vor dem Checkout und actions/checkout@v7 als Abhilfe festgehalten¹

Siehe auch

• Host-System
• Gitea - Git-Dienst
• Gitea Actions - CI/CD-Plattform
• Container-Plattform
• Secrets-Verwaltung
• Behebung des Actions-Cache-Server-Problems

Fußnoten

Beziehungen

• uses: Gitea
• hosts: Gitea Actions

---

1. Source - Conversation - Versioning CI-CD and Content Migration Session 2026-08-30 ↩︎