Logo

Troubleshooting für Ihren ersten Rollout

Ihre erste Distribution durchführen

Troubleshooting für Ihren ersten Rollout

Diese Lektion gibt Ihnen eine kleine Troubleshooting-Routine an die Hand — für jeden Fall, in dem ein Rollout falsch aussieht.

Für Troubleshooting auf Einsteiger-Niveau reichen diese Kommandos:

divekit doctor
divekit dev
divekit config hosts list
divekit overview -d M0

Außerdem sollten Sie bereit sein, diese Dateien direkt zu öffnen:

  • .divekit/distributions/M0/config.json
  • .divekit/distributions/M0/individuals.json
  • .divekit/distributions/M0/remotes.json
  • .divekit/individualization.json

Eine einfache Troubleshooting-Reihenfolge

Wenn etwas falsch aussieht, debuggen Sie in dieser Reihenfolge.

1. Die Umgebung erneut prüfen

divekit doctor

2. Das Host-Setup erneut prüfen

divekit config hosts list

Wenn die Authentifizierung verdächtig aussieht, erneuern Sie sie mit:

divekit auth

3. Das lokale Individualisierungs-Setup erneut prüfen

divekit dev

4. Die Distributionskonfiguration erneut prüfen

Öffnen Sie .divekit/distributions/M0/config.json und verifizieren Sie:

  • remote
  • groupId
  • den optionalen name-Schlüssel, falls Sie einen ergänzt haben — ohne ihn heißen die Repositories standardmäßig M0-<uuid>

5. Den generierten Zustand erneut prüfen

Öffnen Sie individuals.json und remotes.json.

6. Das Remote-Ergebnis in GitLab erneut prüfen

Vergleichen Sie die tatsächlichen Repositories mit dem, was die lokalen Zustandsdateien behaupten.

Diese Reihenfolge bewegt sich von breiten Umgebungsproblemen hin zum konkreten Distributionszustand.

Schnelle Diagnosehilfe

Symptom Erster Blick Warum
nichts wurde erstellt doctor, Host-Setup, groupId breite Umgebungs- oder Zielkonfigurationsfehler kommen zuerst
Namen sehen falsch aus config.json und overview Benennungsfehler zeigen sich meist vor tieferer Zustandsanalyse
Mitglieder fehlen divekit members list und Ihre Mitglieder-Eingabe Remote-Mitgliedschaft hängt von gültiger Eingabe ab
Inhalte wurden nicht individualisiert divekit dev, Platzhalter in der Vorlage, individualization.json, individuals.json das Problem liegt meist in der Variationskette

Wiederholen und Aufräumen

Diese Werkzeuge brauchen Sie im normalen Einsteiger-Workflow nicht, aber Sie sollten wissen, dass es sie gibt.

--add

Das verteilt an konfigurierte Mitglieder, die im bestehenden Distributionszustand noch fehlen — zum Beispiel, nachdem Sie sie mit divekit members add ergänzt haben.

--fresh

Das setzt individuals.json und remotes.json vor dem erneuten Verteilen zurück. Es berührt nur den lokalen Zustand: Repositories, die auf GitLab bereits existieren, werden nicht gelöscht und werden zu Waisen.

Eine sichere Einsteigerregel lautet:

  • verwenden Sie --fresh nur, wenn Sie exakt erklären können, warum der bestehende Zustand neu aufgebaut werden soll

divekit purge

Das löscht die Repositories einer Distribution auf GitLab. Divekit zeigt zuerst einen Löschplan und fragt nach Bestätigung.

Verstehen Sie den Wirkungsbereich, bevor Sie es jemals verwenden: Der Plan wird aus der Ziel-Gruppe gebaut, nicht aus remotes.json.
purge listet jedes Repository, das aktuell in der konfigurierten Gruppe existiert — auch Repositories, die Divekit nie erstellt hat. Übersprungen werden nur Repositories, die GitLab bereits zur Löschung vorgemerkt hat.

In diesem Kurs ist das unbedenklich, weil Ihre Ziel-Gruppe nichts außer den generierten Test-Repositories enthält.
In echten Setups richten Sie Distributionen nur auf Gruppen, die ausschließlich verteilte Repositories enthalten — und lesen Sie den Löschplan immer, bevor Sie bestätigen.

Einen missglückten ersten Rollout wiederholen

  1. die erstellten Repositories mit divekit purge -d M0 löschen
  2. das eigentliche Problem in der Config oder Individualisierung beheben
  3. divekit distribute -d M0 erneut ausführen — --fresh nur ergänzen, wenn Sie auch frischen lokalen Zustand und neue Individualisierungs-Entscheidungen wollen

Typische Fehler

Was Sie versuchen können
Prüfen Sie Host-Setup, Token-Gültigkeit, groupId und ob die lokale Validierung bereits auf ein Problem hingewiesen hat.
Was Sie versuchen können
Standardmäßig heißen Repositories <distribution>-<uuid> — prüfen Sie also zuerst den Distributionsnamen. Falls Sie einen optionalen name-Schlüssel in config.json ergänzt haben, prüfen Sie auch dieses Muster.
Was Sie versuchen können
Inspizieren Sie die konfigurierten Mitglieder mit divekit members list und prüfen Sie, ob diese Bezeichner auf der Ziel-GitLab-Umgebung gültig sind.
Was Sie versuchen können

Prüfen Sie divekit dev, die Platzhalter-Schreibweise in der Vorlage, individualization.json und individuals.json.

Wenn individuals.json die richtigen Entscheidungen festhält, der Repository-Inhalt sie aber nicht widerspiegelt, vergleichen Sie die Quelldateien genauer.

Check

Wählen Sie eine der folgenden kleinen Änderungen und inspizieren Sie die Konsequenzen sorgfältig:

  1. einen optionalen name-Schlüssel wie "name": "project-{{uuid}}" in config.json ergänzen, die Wirkung lokal inspizieren und ihn wieder entfernen
  2. eine weitere Variationsoption in individualization.json ergänzen
  3. individuals.json erneut öffnen und mit overview vergleichen
Vorschlag zur Antwort
config.json für Ziel- und Benennungsänderungen, individualization.json für Variationsänderungen und die generierten Zustandsdateien (individuals.json, remotes.json), um zu sehen, was ein Rollout tatsächlich produziert hat.
Vorschlag zur Antwort
doctor ist gesund, keine unaufgelösten Platzhalter übrig, der Host-Alias existiert, config.json zeigt auf den beabsichtigten Host und die beabsichtigte Gruppe, und individualization.json passt zu den Platzhaltern der Vorlage.

Ihren M0-Test-Rollout aufräumen

Die zwei M0-Repositories aus diesem Abschnitt waren nur eine Lernübung.
Lassen Sie sie nicht auf der geteilten GitLab-Instanz liegen — löschen Sie sie jetzt:

divekit purge -d M0

Divekit listet die Repositories in der Ziel-Gruppe, zeigt einen Löschplan und fragt nach Bestätigung:

$ divekit purge -d M0

┃  # Deletion Plan
┃
┃  https://gitlab.git.nrw/your-group
┃  └─ work
┃     ├─ M0-b8520e99-2bad-c0de-b61c-1249a10f7a5a
┃     └─ M0-a70decaf-bad7-4c95-b211-d0bc95f48204

Are you sure you want to delete 2 repositories?

  Yes      No

Deleted repositories: 2/2
Deleted 2 repositories

Drei Details sind gut zu wissen:

  • der Plan umfasst die gesamte Ziel-Gruppe: purge würde auch Repositories in dieser Gruppe listen, die Divekit nie erstellt hat — lesen Sie den Plan also, bevor Sie bestätigen; zeigt er mehr als Ihre Test-Repositories, antworten Sie mit No
  • je nach Instanz-Einstellungen kann GitLab die gelöschten Repositories noch eine Weile als zur Löschung vorgemerkt anzeigen — das ist GitLabs verzögertes Löschen, kein fehlgeschlagener purge
  • purge löscht nur die Remote-Repositories; die lokalen Zustandsdateien (individuals.json, remotes.json) bleiben unangetastet

Das war zugleich Ihr erster echter divekit purge-Lauf.
Die Abschlussübung endet mit demselben Aufräumschritt — behandeln Sie ihn ab jetzt als festen Bestandteil jedes Test-Rollouts.