# 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 <repo>-temp && git clone https://USER:TOKEN@git.tobisniceshomelab.ddnsfree.com/USER/<repo>.git <repo>-temp
```

### 2. Branch von origin/main erstellen

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

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

### 3. Files kopieren, committen

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

### 4. Pushen

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

### 5. PR via REST API erstellen

```bash
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)

```bash
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):
   ```bash
   ~/.hermes/scripts/gitea-repo-create.sh <name> "<Kurzbeschreibung>"
   ```
   Die letzte Ausgabezeile ist `CLONE <URL>` — diese merken.

2. **Lokal klonen**:
   ```bash
   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**:
   ```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 <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/`._