pamietnik/infra/gitea-actions.md

Gitea Actions — Verwendung & Referenz

Grundprinzip

Gitea Actions ist kompatibel mit GitHub Actions Syntax. Workflow-Dateien liegen in .gitea/workflows/*.yml im Repository. Bei Push auf main wird der Workflow automatisch ausgeführt.

Push → Gitea → act_runner auf NAS → Job-Container (docker:latest) → Deploy

---

Workflow-Struktur

name: Deploy to NAS          # Anzeigename in Gitea UI

on:
  push:
    branches: [main]         # Trigger: Push auf main

jobs:
  deploy:                    # Job-Name
    runs-on: self-hosted     # Welcher Runner-Typ
    container:
      image: docker:latest   # Job läuft in diesem Container
      options: -v /volume2/docker:/volume2/docker  # Volume-Mounts

    steps:
      - name: Schritt 1
        run: echo "Shell-Befehl"

      - name: Schritt 2
        run: |
          echo "Mehrzeiliger"
          echo "Shell-Block"

---

Expressions

Werte aus Gitea zur Laufzeit einsetzen:

Expression	Quelle	Beispiel
${{ secrets.NAME }}	Secrets (maskiert in Logs)	${{ secrets.DB_PASSWORD }}
${{ vars.NAME }}	Variables (sichtbar in Logs)	${{ vars.DEPLOY_DIR }}
${{ github.repository }}	Repo-Metadaten	christoph/pamietnik
${{ github.sha }}	Aktueller Commit-Hash	abc1234...

Secrets vs Variables:

• Secrets → Passwörter, Tokens, API-Keys (secrets.NAME)
• Variables → Pfade, Ports, Namen, alles Nicht-Sensible (vars.NAME)

Setzen unter: Repository → Einstellungen → Actions → Secrets / Variables

---

act_runner auf der NAS

Der Runner empfängt Jobs von Gitea und führt sie aus.

Laufender Container

sudo docker ps | grep gitea-runner
sudo docker logs gitea-runner -f    # Live-Logs

Konfiguration

/volume2/docker/gitea-runner/config.yaml:

runner:
  name: "nas-runner"

container:
  valid_volumes:
    - /volume2/docker           # Erlaubt Volume-Mounts in Job-Containern

Wichtige Einschränkungen auf Synology

• GITEA_INSTANCE_URL muss NAS-IP sein (192.168.1.4:3000), nicht localhost → Job-Container sehen localhost als sich selbst, nicht als NAS
• Docker-Socket wird automatisch in Job-Container propagiert → nicht nochmals in container.options mounten (→ Duplicate-Fehler)
• valid_volumes in config.yaml pflegen, sonst werden Mounts ignoriert

---

Job-Container: docker:latest

Für Deployments wird docker:latest als Job-Container verwendet:

container:
  image: docker:latest
  options: -v /volume2/docker:/volume2/docker

Was ist enthalten:

• Docker CLI (docker, docker compose)
• wget, sh, git
• Nicht enthalten: curl, bash (nur sh)

Volume-Mount -v /volume2/docker:/volume2/docker: Macht den NAS-Dateipfad im Container verfügbar — notwendig damit git clone, .env schreiben und docker compose auf die richtigen Dateien zugreifen.

---

Secrets & Variables anlegen

Gitea UI:

1. Repository → Einstellungen → Actions
2. "Secrets" für Passwörter/Tokens → secrets.NAME
3. "Variables" für Konfiguration → vars.NAME

Typische Variablen pro Projekt:

Name	Typ	Beispielwert
DEPLOY_DIR	Variable	/volume2/docker/pamietnik
APP_PORT	Variable	9050
DB_USER	Variable	pamietnik
DB_NAME	Variable	pamietnik
DB_PASSWORD	Secret	<passwort>

Achtung: Keine Leerzeichen am Ende von Variable-Werten — führt zu Parsing-Fehlern in Expressions.

---

Workflow-Status überwachen

Gitea UI: Repository → Actions → laufenden/letzten Job anklicken

Runner-Logs live:

sudo docker logs gitea-runner -f

Job neu triggern (leerer Commit):

git commit --allow-empty -m "ci: retrigger deploy" && git push

---

Fehlersuche

Fehler	Ursache	Lösung
connection refused :3000	localhost statt NAS-IP	GITEA_INSTANCE_URL=http://192.168.1.4:3000
Duplicate mount point	Socket doppelt gemountet	Nur einmal in container.options oder nur Runner-Mount
not a valid volume, will be ignored	valid_volumes fehlt	In config.yaml eintragen
curl: not found	nicht in docker:latest	wget -qO- verwenden
cannot find node in PATH	actions/checkout@v4 braucht Node	Stattdessen git clone/pull direkt verwenden
Variable leer (/docker-compose.yml)	Als Secret statt Variable gesetzt	Unter Variables (nicht Secrets) anlegen