# Forgejo Issues zu Markdown Export - Anleitung

Diese Anleitung erklärt, wie du den Forgejo-to-Markdown Exporter einrichten und verwenden kannst, um Issues in Markdown-Dateien zu exportieren und sie für Knowledge-Management-Tools wie MSTY zu nutzen.

## Überblick

Der Exporter bietet folgende Funktionen:

- Export aller Issues eines Repositories oder einer Organisation in Markdown-Dateien
- Inkrementelle Updates (nur geänderte Issues werden aktualisiert)
- Einbeziehung von Kommentaren und Metadaten
- Formatierung als strukturierte Markdown-Dokumente
- Erstellung einer Indexdatei für den einfachen Zugriff

## Installation

### Voraussetzungen

- Python 3.11 oder höher
- Internetverbindung zum Forgejo-Server
- Berechtigungen zum Lesen der Forgejo-Issues

### Einrichtung

1. Speichere das Skript 
Am besten installierst du den Exporter über den befehl `git clone https://git.rpi-virtuell.de/joachim-happel/git_issue_importer.git` danach wechselst eu in das Verzeichnis mit `cd git_issue_importer`

2. Kopiere die Datei .env.template nach .env und setze die URl zu deiner forgejo Instanz:

```text
FORGEJO_URL = "https://git.rpi-virtuell.de"
FORGEJO_TOKEN = "dein-token"
```
den Token kannst du unter  https://git.rpi-virtuell.de/user/settings/applications generieren

3. Installiere die erforderlichen Abhängigkeiten:

```bash
pip install requests python-dotenv
```


## Verwendung

### Grundlegende Verwendung

Führe das Skript mit den erforderlichen Parametern aus:

```bash
python forgejo_exporter.py --owner "Comenius-Institut" --repo "FOERBICO" --output "./forgejo_issues"
```

### Alle verfügbaren Parameter

```
--owner    : Repository-Besitzer (Benutzer oder Organisation) [erforderlich]
--repo     : Repository-Name oder 'all' für alle Repositories [erforderlich]
--output   : Ausgabeordner für Markdown-Dateien [Standard: ./forgejo_issues]
--comments : Kommentare einbeziehen [optional Flag]
--closed   : Geschlossene Issues einbeziehen [optional Flag]
```

### Beispiele

**Export eines einzelnen Repositories mit Kommentaren:**
```bash
python forgejo_exporter.py --owner "Comenius-Institut" --repo "FOERBICO" --output "./forgejo_issues" --comments
```

**Export aller Repositories einer Organisation inkl. geschlossener Issues:**
```bash
python forgejo_exporter.py --owner "Comenius-Institut" --repo "all" --output "./forgejo_issues" --closed
```

**Export mit allen Optionen:**
```bash
python forgejo_exporter.py --owner "Comenius-Institut" --repo "FOERBICO" --output "./forgejo_issues" --comments --closed
```

## Automatisierung

Um die Aktualisierung zu automatisieren, kannst du das bereitgestellte Bash-Skript verwenden:

1. Speichere das Bash-Skript als `update_forgejo.sh`
2. Mache es ausführbar: `chmod +x update_forgejo.sh`
3. Passe die Einstellungen im Skript an (Repository-Besitzer, Repository-Name)
4. Führe es manuell aus oder richte einen Cron-Job ein

### Einrichtung eines Cron-Jobs für regelmäßige Updates

Öffne die Crontab-Konfiguration:
```bash
crontab -e
```

Füge eine Zeile für tägliche Aktualisierungen hinzu:
```
# Aktualisiere Forgejo-Issues jeden Tag um 3:00 Uhr
0 3 * * * /pfad/zu/update_forgejo.sh
```

## Ausgabestruktur

Nach der Ausführung des Skripts enthält der Ausgabeordner folgende Dateien:

- `index.md`: Eine Übersicht aller Issues, gruppiert nach Repository
- `_metadata.json`: Metadaten für inkrementelle Updates (nicht löschen!)
- Einzelne Markdown-Dateien für jedes Issue, mit dem Namensformat:
  `{repository_owner}_{repository_name}__issue_{number}_{title}.md`

### Struktur einer Issue-Datei

Jede generierte Markdown-Datei enthält:

1. **Titel und Issue-ID**
2. **Metadaten** (Repository, Autor, Status, Daten, URL)
3. **Labels** (falls vorhanden)
4. **Milestone** (falls vorhanden)
5. **Beschreibung** des Issues
6. **Kommentare** (wenn mit `--comments` aktiviert)

## Integration mit Knowledge-Management-Tools

### Verwendung mit MSTY

1. Wähle den Ausgabeordner als Knowledge Stack in MSTY
2. Klicke auf Compose (kann einige Minuten dauern)
3. Führe das Update-Skript und Compose regelmäßig aus, um die Wissensdatenbank aktuell zu halten