mission-control-v2/docs/skills/gitea-workflow.md

gitea-workflow — Git- und Gitea-REST-API-Workflows

Kurz: Wenn das Repo schreibgeschützt ist (Faden 8 / R2), arbeitet der Agent über einen sauberen Clone in /tmp und erstellt einen PR via Gitea-REST-API statt direkt zu pushen.

Was der Skill tut

Der Skill beschreibt einen alternativen Git-Workflow für Fälle, in denen der direkte Schreibzugriff auf ein Repo blockiert ist (insbesondere das mission-control-v2-Repo unter Faden 8/R2). Statt direkt zu committen, wird:

1. Ein frischer Clone in /tmp erstellt.
2. Ein Feature-Branch von origin/main abgezweigt.
3. Änderungen im Clone gemacht, committet, gepusht.
4. Ein Pull Request via Gitea-REST-API auf main erstellt.

Das Ergebnis landet als Vorschlags-Branch auf Gitea und geht über das Auftragsbuch ins Live-System — der Commander muss es annehmen.

Wann er zum Einsatz kommt

Situation	Aktion
Repo hat Schreibschutz (Faden 8 / R2)	Gitea-Workflow (diese Datei)
Neues Projekt wird vorbereitet	gitea-repo-create.sh + Gerüst aufbauen
Normaler Repo-Zugriff ist erlaubt	Direkter Git-Workflow (Branch → Commit → Push)

Konfiguration

Zugangsdaten

• Gitea-URL: https://git.tobisniceshomelab.ddnsfree.com
• User: Hitonabi
• Token: In .git-credentials oder Config-Files hinterlegt (Scope write:repository)
• Repo-Anlege-Token: In ~/.config/gitea/create-token (dediziertes write:user-Token)

Token-Unterschied

Token	Ort	Scope	Einsatz
Push/PR-Token	~/.git-credentials	write:repository	Branch-Push, PR erstellen
Repo-Anlege-Token	~/.config/gitea/create-token	write:user	Nur Repo-Anlage über gitea-repo-create.sh

Ein Repo kann nur mit dem write:user-Token angelegt werden — der Push-Token reicht nicht. Nie per Roh-curl erzwingen.

Arbeitsablauf (Schritt-für-Schritt)

1. Sauberen Clone erstellen

cd /tmp && rm -rf <repo>-temp && git clone https://USER:TOKEN@git.tobisniceshomelab.ddnsfree.com/USER/<repo>.git <repo>-temp

2. Branch von origin/main erstellen

cd /tmp/<repo>-temp && git checkout -b <branch-name> origin/main

Branch-Namen mit / (z. B. doku/gitea-skill) funktionieren.

3. Files kopieren, committen

cp <quelle> <repo>-temp/<pfad>
git add <pfad> && git commit -m "<commit-nachricht>"

4. Pushen

cd /tmp/<repo>-temp && git push origin <branch-name>

5. PR via REST API erstellen

curl -sL -X POST "https://git.tobisniceshomelab.ddnsfree.com/api/v1/repos/<owner>/<repo>/pulls" \
  -H "Authorization: token <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"title": "<PR-Titel>", "body": "<PR-Body>", "head": "<branch-name>", "base": "main"}'

6. Main-SHA abrufen (falls nötig)

curl -sL "https://git.tobisniceshomelab.ddnsfree.com/api/v1/repos/<owner>/<repo>/git/refs/heads/main" \
  -H "Authorization: token <TOKEN>"

Neues Projekt vorbereiten (seit 17.07.2026)

Bei einem neuen Projekt wird nicht nur der Workflow angewendet, sondern das komplette Gerüst gelegt:

1. Repo anlegen (privat, initialisiert):

   ~/.hermes/scripts/gitea-repo-create.sh <name> "<Kurzbeschreibung>"
   

   Die letzte Ausgabezeile ist CLONE <URL> — diese merken.

2. Lokal klonen:

   git clone <clone-url> /tmp/<name> && cd /tmp/<name>
   

3. Dateistruktur aufbauen (nur das Gerüst):

   • README.md mit Ziel/Scope
   • .gitignore passend zur Sprache
   • Grundordner (src/, docs/, tests/) mit Platzhaltern
   • AGENTS.md (Projekt-Kontext für spätere Desktop-Arbeit)
   • Kein fertiger Code — nur das Skelett, das der Commander in Hermes Desktop weiterbaut

4. Committen + pushen:

   git add -A && git commit -m "Projekt-Gerüst: Struktur + README" && git push
   

5. Clone-Fallback (wenn Zielordner schon existiert):

   git rm -r --cached . 2>/dev/null; rm -rf .git
   git init && git remote add origin <url>
   git fetch origin
   git checkout -b main origin/main
   git checkout origin/<branch> -- .
   

6. Übergeben: Commander die Repo-URL melden + kurz beschreiben, was vorbereitet wurde.

Pitfalls

Falle	Vermeidung
Blobs direkt über /git/blobs erstellen → 404	Niemals; immer git add + Commit nutzen
Push/PR-Token reicht nicht für Repo-Anlage	gitea-repo-create.sh mit write:user-Token nutzen
Repo-Anlage per Roh-curl erzwingen	Nie — Token-Berechtigungen sind serverseitig, das Skript ist der einzige Weg
Grosse Dateien am Stück lesen → Kontext sprengt	Gezielt lesen über Zeilenbereiche (read_file mit offset/limit)
Direkt in Live-Checkout schreiben → Faden 8	Immer im frischen Klon arbeiten, Vorschlagsbranch via PR

Konsistenz mit MC2-Konventionen

• Sprache: Deutsch, direkt, kein Marketing-Sprech.
• Struktur: Kurze Beschreibung → Wann einsetzen → Konfiguration → Arbeitsablauf → Pitfalls → Konsistenz.
• Querverweise: Verweise auf Faden 8/R2, Auftragsbuch, gitea-repo-create.sh.
• Tabellen: Wo sinnvoll (Situationen, Konfiguration, Pitfalls) als Tabelle formatiert.
• Code-Blöcke: Alle Befehle als bash-Code-Blöcke mit klaren Variablen-Platzhaltern.
• Keine Secrets: Tokens werden referenziert (Ort), nicht ausgeschrieben.

---

Diese Datei wurde als Skill-Dokumentation im MC2-Repo erstellt. Sie ist Teil der Skills-Docs in docs/skills/.