Anleitung: Issues und Meilensteine zwischen Forgejo-Repositories übertragen

Voraussetzungen

1. API-Token erstellen: Generiere persönliche Zugriffstoken für beide Forgejo-Repositories (Quell- und Zielrepo).

   • Gehe zu deinem Profil > Einstellungen > Anwendungen > Token generieren.
   • Besuche dazu: https://git.rpi-virtuell.de/user/settings/applications.
   • Setze folgende Berechtigungen:
     • Issue: Lesen und Schreiben
     • Repository: Lesen und Schreiben (falls Meilensteine angelegt werden müssen)
   • Notiere das Token sicher als ZUGRIFFS_TOKEN.

2. Tools installieren:

   • Richte eine virtuelle Python-Umgebung ein:

     python3 -m venv venv
     source venv/bin/activate   # Linux/macOS
     venv\Scripts\activate    # Windows
     

   • Installiere die benötigten Pakete:

     pip install requests
     

   • Stelle sicher, dass curl und jq installiert sind (für Linux/MacOS):

     sudo apt install curl jq # Ubuntu/Debian
     brew install curl jq     # macOS
     

   • Installiere Visual Studio Code (falls nicht bereits vorhanden):
     • Download VS Code
     • Füge die Erweiterung Python hinzu.

---

Schritt 1: Meilensteine aus dem Quellrepository exportieren

1. API-Endpoint nutzen:

   • Führe folgenden Befehl aus, um die Meilensteine als JSON herunterzuladen:

     curl -H "Authorization: token ZUGRIFFS_TOKEN" \
          -H "Content-Type: application/json" \
          "https://forgejo.example.com/api/v1/repos/SOURCE_USER/SOURCE_REPO/milestones" > milestones.json
     

2. JSON-Daten prüfen:

   • Öffne die Datei milestones.json und überprüfe, ob alle relevanten Meilensteine korrekt exportiert wurden.

---

Schritt 2: Issues aus dem Quellrepository exportieren

1. Issues herunterladen:

   • Führe folgenden Befehl aus, um alle Issues herunterzuladen (inkl. geschlossener):

     curl -H "Authorization: token ZUGRIFFS_TOKEN" \
          -H "Content-Type: application/json" \
          "https://forgejo.example.com/api/v1/repos/SOURCE_USER/SOURCE_REPO/issues?state=all" > issues.json
     

2. JSON-Daten prüfen und bereinigen:

   • Öffne die Datei issues.json in einem Editor wie Visual Studio Code.
   • Stelle sicher, dass die Labels als Array von Strings vorliegen, z. B.:

     "labels": ["bug", "enhancement"]
     

   • Entferne alle ungültigen Zeichen oder fehlerhaften Strukturen, die das Parsen behindern könnten.
   • Prüfe, ob das JSON korrekt formatiert ist, z. B. mit einem JSON-Validator.

---

Schritt 3: Daten lokal bearbeiten

1. Meilensteine anpassen:

   • Öffne milestones.json in Visual Studio Code oder einem Texteditor deiner Wahl.
   • Ändere Felder wie title, description oder due_on bei Bedarf.

2. Issues bearbeiten:

   • Öffne issues.json in Visual Studio Code.
   • Passe Felder wie title, body, labels oder assignees an.
   • Stelle sicher, dass alle Referenzen wie milestone_id korrekt sind.

---

Schritt 4: Meilensteine ins Zielrepository importieren

1. API-Endpoint nutzen:

   • Lade die Meilensteine in das Zielrepository hoch:

     jq -c '.[]' milestones.json | while read milestone; do
         curl -X POST -H "Authorization: token ZUGRIFFS_TOKEN" \
              -H "Content-Type: application/json" \
              -d "$milestone" \
              "https://forgejo.example.com/api/v1/repos/TARGET_USER/TARGET_REPO/milestones"
     done
     

2. Ergebnisse prüfen:

   • Gehe ins Zielrepository und überprüfe die Meilensteine.

---

Schritt 5: Issues ins Zielrepository importieren

1. API-Endpoint nutzen:

   • Lade die Issues in das Zielrepository hoch:

     jq -c '.[]' issues.json | while read issue; do
         curl -X POST -H "Authorization: token ZUGRIFFS_TOKEN" \
              -H "Content-Type: application/json" \
              -d "$issue" \
              "https://forgejo.example.com/api/v1/repos/TARGET_USER/TARGET_REPO/issues"
     done
     

2. Fehlerbehebung bei Importproblemen:

   • Falls der Fehler cannot unmarshal number { into Go struct auftritt, prüfe die Labels in der Datei issues.json. Labels müssen ein Array von Strings sein.
   • Falls der Fehler expected comma after object element auftritt, ist das JSON fehlerhaft. Nutze einen Validator, um die Datei zu korrigieren.

---

Schritt 6: Daten validieren

1. Datenüberprüfung:

   • Öffne das Zielrepository und prüfe:
     • Sind alle Meilensteine vorhanden?
     • Wurden alle Issues korrekt übertragen (inkl. Labels und Zuweisungen)?

2. Fehlerbehebung:

   • Bei Problemen erneut die JSON-Daten prüfen und die oben genannten Schritte wiederholen.

---

Zusätzliche Hinweise

• Nutze Python oder Skripte für komplexere Automatisierungen (siehe vorherige Anleitung).
• Dokumentiere Anpassungen in einem Logbuch, um Änderungen nachvollziehbar zu machen.
• Teste den Ablauf zuerst in einem Testrepository.