From 7e2e8bdf59ab7b99cb33e8de4ffeec66ca4939b6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Runden?= <br@chamaeleoncloud.de>
Date: Tue, 28 Jul 2026 15:56:49 +0200
Subject: [PATCH] =?UTF-8?q?Projektsupt=20als=20skeleton=20um=20git-festleg?=
 =?UTF-8?q?ungen=20erg=C3=A4nzt.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/git-workflow.md | 93 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 93 insertions(+)
 create mode 100644 docs/git-workflow.md

diff --git a/docs/git-workflow.md b/docs/git-workflow.md
new file mode 100644
index 0000000..01ac51b
--- /dev/null
+++ b/docs/git-workflow.md
@@ -0,0 +1,93 @@
+# Git Workflow & Deployment Specification
+
+Dieses Dokument beschreibt den standardisierten Release-Ablauf und die CI/CD-Logik für Gitea.
+
+---
+
+## 1. Branching-Modell
+
+Wir nutzen einen vereinfachten, stabilen Release-Workflow mit zwei Haupt-Branches:
+
+* **`main` (Development / Spielwiese):**
+  * Tägliche Entwicklung, Experimente, lokale Tests (venv / local Docker).
+  * Änderungen werden direkt hier committet oder aus Feature-Branches hineingemergt.
+* **`stable` (Production / Freeze):**
+  * Spiegelt exakt den Live-Stand der Produktion wider.
+  * Direct Commits sind tabu. Änderungen gelangen **ausschließlich per Merge aus `main`** hierhin.
+
+---
+
+## 2. Release-Ablauf (Dev nach Prod)
+
+Sobald ein Stand auf `main` lokal getestet und einsatzbereit ist:
+
+### Variante A: Via Terminal (CLI)
+```bash
+# 1. Lokalen Stand auf main sichern
+git checkout main
+git pull
+
+# 2. Auf stable wechseln und main hineinmergen
+git checkout stable
+git merge main
+
+# 3. Release nach Gitea pushen (Triggert CI/CD)
+git push origin stable
+
+# 4. Zurück auf main für die weitere Entwicklung
+git checkout main
+
+```
+
+### Variante B: Via VSCodium Git-UI
+
+1. Unten links den Branch von `main` auf `stable` wechseln.
+2. Befehlspalette öffnen (`Ctrl + Shift + P`) -> `Git: Branch mergen...` -> **`main`** auswählen.
+3. Auf **Änderungen synchronisieren** (Push) klicken.
+4. Unten links wieder zurück auf **`main`** wechseln.
+
+---
+
+## 3. Gitea Runner & Deployment Logic
+
+Der Rebuild auf dem Produktionsserver wird vollautomatisch über Gitea Actions getriggert.
+
+* **Trigger:** Das Deployment startet **nur**, wenn Änderungen auf den Branch `stable` gepushed werden.
+* **Workflow-Datei:** `.gitea/workflows/deploy.yml`
+
+### `.gitea/workflows/deploy.yml` Template:
+
+```yaml
+name: Production Deployment
+
+on:
+  push:
+    branches:
+      - 'stable'
+
+jobs:
+  deploy:
+    runs-on: self-hosted
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v3
+
+      - name: Rebuild & Restart Docker Containers
+        run: |
+          docker compose down
+          docker compose up --build -d --pull always
+          docker image prune -f
+
+```
+
+---
+
+## 4. Regeln für AI-Agenten (Vibe / Roo Code)
+
+* Agenten arbeiten **ausschließlich auf dem `main`-Branch**.
+* Agenten dürfen niemals eigenständig einen Merge auf `stable` durchführen oder Commits auf `stable` pushen.
+* Das Erstellen von `.env` Dateien auf `stable` ist untersagt (Nutzung der Server-Umgebungsvariablen via `.env.example`).
+
+```
+
+---