128 lines
4 KiB
Markdown
128 lines
4 KiB
Markdown
# 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
|