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:

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:

pip install requests python-dotenv

Verwendung

Grundlegende Verwendung

Führe das Skript mit den erforderlichen Parametern aus:

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:

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

Export aller Repositories einer Organisation inkl. geschlossener Issues:

python forgejo_exporter.py --owner "Comenius-Institut" --repo "all" --output "./forgejo_issues" --closed

Export mit allen Optionen:

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:

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