From 11c341657191a0055264a7c983c9467f1bc4ecc4 Mon Sep 17 00:00:00 2001 From: Tobi Date: Tue, 21 Jul 2026 03:53:59 +0200 Subject: [PATCH] Doku: gitea-workflow Skill dokumentieren --- docs/skills/gitea-workflow.md | 146 ++++++++++++++++++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 docs/skills/gitea-workflow.md diff --git a/docs/skills/gitea-workflow.md b/docs/skills/gitea-workflow.md new file mode 100644 index 0000000..0a0e79c --- /dev/null +++ b/docs/skills/gitea-workflow.md @@ -0,0 +1,146 @@ +# 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 + +```bash +cd /tmp && rm -rf -temp && git clone https://USER:TOKEN@git.tobisniceshomelab.ddnsfree.com/USER/.git -temp +``` + +### 2. Branch von origin/main erstellen + +```bash +cd /tmp/-temp && git checkout -b origin/main +``` + +Branch-Namen mit `/` (z. B. `doku/gitea-skill`) funktionieren. + +### 3. Files kopieren, committen + +```bash +cp -temp/ +git add && git commit -m "" +``` + +### 4. Pushen + +```bash +cd /tmp/-temp && git push origin +``` + +### 5. PR via REST API erstellen + +```bash +curl -sL -X POST "https://git.tobisniceshomelab.ddnsfree.com/api/v1/repos///pulls" \ + -H "Authorization: token " \ + -H "Content-Type: application/json" \ + -d '{"title": "", "body": "", "head": "", "base": "main"}' +``` + +### 6. Main-SHA abrufen (falls nötig) + +```bash +curl -sL "https://git.tobisniceshomelab.ddnsfree.com/api/v1/repos///git/refs/heads/main" \ + -H "Authorization: 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): + ```bash + ~/.hermes/scripts/gitea-repo-create.sh "" + ``` + Die letzte Ausgabezeile ist `CLONE ` — diese merken. + +2. **Lokal klonen**: + ```bash + git clone /tmp/ && cd /tmp/ + ``` + +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**: + ```bash + git add -A && git commit -m "Projekt-Gerüst: Struktur + README" && git push + ``` + +5. **Clone-Fallback** (wenn Zielordner schon existiert): + ```bash + git rm -r --cached . 2>/dev/null; rm -rf .git + git init && git remote add origin + git fetch origin + git checkout -b main origin/main + git checkout origin/ -- . + ``` + +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/`._