GitLab-Upgrade: alle Stolpersteine im Überblick

Ein GitLab über mehrere Hauptversionen zu heben ist ein Ablauf mit vielen Abhängigkeiten. Datenbank-Migrationen bauen aufeinander auf, PostgreSQL-Mindestversionen wandern mit, Konfigurationsschlüssel verschwinden, Rake-Tasks werden umbenannt, und ein Backup ist nur unter genau einer Version und Edition wieder einspielbar. Der Hauptbeitrag GitLab über mehrere Versionen upgraden beschreibt den Weg selbst und greift die vier folgenreichsten dieser Fälle heraus. Diese Seite führt alle auf.

Gedacht ist die Sammlung für zwei Situationen. Erstens für die Planung: Gehen Sie die Fälle durch, bevor das Wartungsfenster steht, und prüfen Sie mit den angegebenen Befehlen, welche davon auf Ihre Instanz zutreffen. Die meisten lassen sich vorab abräumen und kosten dann keine Downtime. Zweitens für den Ernstfall: Wenn ein Upgrade mitten in der Kette stehen bleibt, finden Sie hier die Meldung und den Weg zurück.

1. Das Upgrade bricht ab, weil eine Migration noch aktiv ist

Symptom: Der Start der nächsten Stufe endet mit der Meldung Expected batched background migration for the given configuration to be marked as 'finished', but it is 'active'.

Ursache: Die Migrationen der vorherigen Stufe waren noch nicht durchgelaufen, als das nächste Image gestartet wurde. Der Required Stop wurde damit faktisch übersprungen.

Prüfung:

sudo gitlab-psql -c "SELECT job_class_name, table_name, column_name, job_arguments FROM batched_background_migrations WHERE status NOT IN(3, 6);"

Die Abfrage muss null Zeilen liefern.

Lösung: Auf die vorherige Version zurück, die Migrationen vollständig durchlaufen lassen, erst dann weiter. Eine hängende Migration lässt sich gezielt abschließen:

sudo gitlab-rake gitlab:background_migrations:finalize[<job_class_name>,<table_name>,<column_name>,'<job_arguments>']

Fehlgeschlagene Batched Background Migrations blockieren jedes weitere Upgrade und müssen zuerst gelöst werden. Das manuelle Als-fertig-Markieren einer Migration ist ein anderer Fall: Die Doku warnt, dass das zu Datenverlust führen und die Instanz schwer reparierbar beschädigen kann, und verlangt vorher Rücksprache mit dem GitLab-Support sowie ein Backup.

2. Der gewohnte Rake-Task existiert nicht mehr

Symptom: gitlab-rake gitlab:background_migrations:status bricht mit einem Don't know how to build task-Fehler ab.

Ursache: Ab GitLab 18.9 heißt der Task gitlab:background_migrations:list. Ältere Runbooks und Skripte laufen ins Leere.

Prüfung:

sudo gitlab-rake gitlab:background_migrations:list

Lösung: Ab 18.9 :list nutzen, Details über gitlab-rake gitlab:background_migrations:show[<migration_id>]. Bis 18.8 bleibt :status gültig. Wenn Sie Runbooks pflegen, versionieren Sie den Befehl mit.

3. gitlab-ctl reconfigure scheitert nach dem Sprung auf 18.0

Symptom: Das Reconfigure bricht ab, Gitaly findet seine Speicherorte nicht.

Ursache: Die Einstellung git_data_dirs ist ab GitLab 18.0 entfernt. Wer sie noch in gitlab.rb stehen hat, muss die Gitaly-Konfiguration vorher migrieren.

Prüfung:

grep -n -E '^[^#]*git_data_dirs' /etc/gitlab/gitlab.rb

Vor dem Upgrade auf 18.0 darf es keinen aktiven Treffer geben.

Lösung: Noch unter der letzten 17er von git_data_dirs auf die gitaly['configuration']-Struktur umstellen, reconfigure laufen lassen, erst dann die Stufe fahren.

4. Die Datenbank ist für die Zielversion zu alt

Symptom: Das Upgrade auf 18.0 oder 19.0 scheitert oder wird blockiert, weil die PostgreSQL-Version nicht ausreicht.

Ursache: PostgreSQL 14 wird ab GitLab 18 nicht mehr unterstützt, GitLab 19 verlangt mindestens PostgreSQL 17. Der Datenbank-Sprung ist ein eigener Schritt vor dem GitLab-Schritt. Wer die Kette 17 nach 18 nach 19 plant, braucht zwei davon.

Prüfung:

sudo gitlab-rake gitlab:env:info | grep -i 'DB Version'

Lösung: Das mitgelieferte PostgreSQL noch unter der jeweils alten GitLab-Version heben, mit sudo gitlab-ctl pg-upgrade -V 16 vor der 18 und sudo gitlab-ctl pg-upgrade -V 17 vor der 19. GitLab 18.11 bringt PostgreSQL 17.7 bereits als Default für Upgrades mit.

5. pg-upgrade bricht wegen Plattenplatz ab

Symptom: Der Aufruf endet mit einem Hinweis auf zu wenig freien Speicherplatz.

Ursache: pg-upgrade legt eine zweite vollständige Kopie der Datenbank an und prüft das vorab. Auf knapp bemessenen Volumes reißt das die Grenze.

Prüfung:

sudo du -sh /var/opt/gitlab/postgresql/data
sudo df -h /var/opt/gitlab

Der freie Platz muss größer sein als die Datenbank.

Lösung: Platz schaffen. Das Flag --skip-disk-check existiert, umgeht aber genau die Schutzprüfung. Die Doku formuliert unmissverständlich, dass ohne ausreichenden freien Platz gar nicht erst gestartet werden soll.

6. Runner registrieren sich nach dem Sprung auf 17.0 nicht mehr

Symptom: Neue Runner lassen sich nach dem Upgrade nicht mehr registrieren.

Ursache: Der alte Registration-Token-Workflow ist ab GitLab 17.0 standardmäßig deaktiviert.

Prüfung: Nach dem Upgrade einen Testrunner registrieren und unter Admin > Runners kontrollieren, ob er online erscheint.

Lösung: Vor dem Upgrade auf den neuen Registrierungs-Workflow mit Authentication Tokens umstellen. Danach ist die 17.0 an dieser Stelle unauffällig.

7. Eine große Instanz hängt beim Sprung über 17.1

Symptom: Lange Downtime und 500er-Fehler beim Sprung von 17.0 auf eine spätere 17er-Version.

Ursache: GitLab 17.1 ist ein zusätzlicher Required Stop für große Instanzen mit vielen Datensätzen in ci_pipeline_messages. Ab mehr als 1,5 Millionen Zeilen ist die Zwischenstufe Pflicht. In der Standard-Stop-Liste fällt das nicht auf.

Prüfung:

sudo gitlab-psql -c "SELECT count(*) FROM ci_pipeline_messages;"

Lösung: Liegt der Wert über 1,5 Millionen, 17.1.8 als Zwischenstufe einplanen, dort alle Batched Background Migrations abwarten und erst danach weiter.

8. Das Backup lässt sich nicht einspielen

Symptom: Der Restore verweigert die Arbeit oder führt zu einer defekten Instanz.

Ursache: Ein Backup lässt sich ausschließlich auf exakt derselben GitLab-Version und derselben Edition zurückspielen, auf der es erstellt wurde. Ein Backup aus 17.11.7 hilft auf einer bereits laufenden 18.2 nicht.

Prüfung: Version der laufenden Instanz gegen das Backup halten.

sudo gitlab-rake gitlab:env:info | grep -i '^Version'
ls -1 /var/opt/gitlab/backups/

Lösung: Pro Stufe ein eigenes Backup ziehen und die Version im Dateinamen mitführen, etwa über BACKUP=<version>-vor-upgrade. Für den Rollback zuerst die passende GitLab-Version installieren, dann den Restore fahren.

9. Nach dem Restore scheitern 2FA und Runner-Authentisierung

Symptom: Nutzer mit Zwei-Faktor-Authentisierung kommen nicht mehr hinein, Runner authentisieren sich nicht.

Ursache: Das Backup enthält die Konfigurationsdateien nicht. Ohne /etc/gitlab/gitlab-secrets.json fehlen die Schlüssel für 2FA und die CI/CD-Variablen.

Prüfung:

sudo gitlab-rake gitlab:doctor:secrets

Lösung: gitlab-secrets.json und gitlab.rb bei jedem Backup separat mitsichern und beim Restore mit zurückspielen. Ein Backup ohne Secrets-Datei ist für einen Rollback wertlos.

10. Das Backup läuft durch, die Datei liegt woanders

Symptom: Der Backup-Lauf meldet keinen Fehler, im erwarteten Verzeichnis liegt nichts.

Ursache: Der Ablageort wird über gitlab_rails['backup_path'] gesetzt, der Default ist /var/opt/gitlab/backups. Wer den Pfad ändert und danach kein reconfigure ausführt, schreibt weiterhin an die alte Stelle.

Prüfung:

ls -lh /var/opt/gitlab/backups/

Die Datei <backup-id>_gitlab_backup.tar muss existieren und eine plausible Größe haben.

Lösung: backup_path in /etc/gitlab/gitlab.rb setzen, sudo gitlab-ctl reconfigure ausführen, danach den tatsächlichen Ausgabepfad des Backup-Laufs kontrollieren, nicht den erwarteten.

11. Der Sprung landet versehentlich auf der neuesten Version

Symptom: Nach dem Paket-Upgrade läuft eine deutlich höhere Version als geplant, Stops wurden übersprungen.

Ursache: sudo apt install gitlab-ee ohne Versionsangabe zieht das aktuellste verfügbare Paket.

Prüfung:

sudo gitlab-rake gitlab:env:info | grep -i '^Version'

Lösung: Pro Stufe explizit versionieren mit sudo apt update && sudo apt install gitlab-ee=<version>-ee.0. Verfügbare Versionen zeigt sudo apt-cache madison gitlab-ee.

12. Die Container Registry erreicht nach dem Sprung auf 19 den Bucket nicht

Symptom: Die Registry startet nicht mehr oder kann den S3-Bucket nicht ansprechen.

Ursache: Der alte s3-Treiber auf Basis von AWS SDK v1 ist in GitLab 19 entfernt. Der Nachfolger s3_v2 verlangt ein URI-Schema im regionendpoint.

Prüfung: Nach dem Upgrade ein Image in ein Testprojekt pushen und wieder pullen, parallel die Registry-Logs auf Storage-Fehler durchsehen.

Lösung: Vor dem Upgrade auf s3_v2 umstellen und dem regionendpoint ein https:// oder http:// voranstellen.

13. Für das Betriebssystem gibt es kein Paket mehr

Symptom: Die Zielversion existiert im Repository für die eingesetzte Distribution nicht.

Ursache: GitLab 19 streicht Ubuntu 20.04 und die SUSE-Distributionen. Damit wird der Betriebssystem-Wechsel selbst zum Pflicht-Zwischenschritt.

Prüfung:

sudo apt-cache madison gitlab-ee

Bietet die Ausgabe die geplante Zielversion nicht an, liegt es nicht am Repository-Cache.

Lösung: Das Betriebssystem vor der betreffenden GitLab-Stufe heben, bei Ubuntu von 20.04 auf 22.04. Bei SUSE auf eine unterstützte Distribution wechseln. Dieser Schritt gehört in den Plan, bevor das Wartungsfenster steht.

14. Das erste Patch-Release der Ziel-Minor zeigt sofort Fehlverhalten

Symptom: Direkt nach dem Upgrade tritt ein reproduzierbarer Defekt auf, der nichts mit der eigenen Konfiguration zu tun hat.

Ursache: Einzelne Patch-Stände haben dokumentierte Known Issues. GitLab nennt für die 18er-Reihe unter anderem fehlschlagende Datenbank-Migrationen mit PostgreSQL-CheckViolation-Fehlern in 18.9.0 bis 18.9.1 und eine CI-Job-Token-Regression in 18.11.0 bis 18.11.1, die das Ziehen von Container-Images aus internen und öffentlichen Projekten verhindert.

Prüfung: Die Seite /update/versions/gitlab_XX_changes/ nach der geplanten Zielversion durchsuchen, bevor das Image gezogen wird.

Lösung: Immer das neueste verfügbare Patch-Release der Ziel-Minor wählen, nie das erste. Die Upgrade-Notes gehören in die Vorbereitung des Wartungsfensters, nicht in die Fehlersuche danach.

15. Advanced Search bricht nach einem Major-Upgrade

Symptom: Die Advanced Search arbeitet nach dem Sprung auf eine neue Hauptversion nicht mehr korrekt.

Ursache: Vor einem Major-Upgrade müssen alle Advanced-Search-Migrationen aus dem letzten Minor-Release der aktuellen Version abgeschlossen sein.

Prüfung:

sudo gitlab-rake gitlab:elastic:list_pending_migrations

Die Liste muss leer sein.

Lösung: Vor dem Major-Sprung die offenen Migrationen abwarten und erst danach die Stufe fahren.

16. Backup und Restore scheitern bei externem PostgreSQL

Symptom: Backup oder Restore brechen mit Fehlern aus pg_dump ab.

Ursache: Bei externem PostgreSQL muss die pg_dump-Client-Version zur Server-Version passen.

Prüfung: Client- und Server-Version gegeneinander halten, bevor Sie sich auf das Backup verlassen.

Lösung: Die Client-Werkzeuge auf dem Host anheben, von dem aus das Backup läuft, sodass sie zur Server-Version passen.

Wie Sie diese Liste einsetzen

Die Fälle 3, 4, 5, 6, 7, 12 und 13 lassen sich vollständig vor dem Wartungsfenster abarbeiten. Sie brauchen dafür keine Downtime, nur die jeweiligen Prüfbefehle gegen die laufende Instanz. Ich halte das für den lohnendsten Teil der Vorbereitung, weil jeder dieser Punkte sonst mitten in der Kette auftaucht, wenn die Instanz bereits abgeschaltet ist.

Die Fälle 1, 2, 8, 9, 10 und 11 betreffen den Ablauf selbst. Sie gehören in das Runbook, das Sie während des Fensters abarbeiten, nicht in die Vorbereitung. Der zugehörige Ablauf mit den Prüfbefehlen nach jedem Schritt steht im Hauptbeitrag GitLab über mehrere Versionen upgraden.

Die Fälle 14, 15 und 16 hängen an Ihrer konkreten Ausstattung. Ob sie zutreffen, entscheidet sich an der gewählten Patch-Version, am Einsatz der Advanced Search und daran, ob PostgreSQL mitgeliefert oder extern betrieben wird.

Sie betreiben Software, die regelmäßig und sicher aktualisiert werden muss? Ich plane und fahre solche Upgrades mit geprüftem Backup und klarem Rollback, im Wartungsfenster statt im Blindflug. Mehr unter Monitoring & Wartung, das Erstgespräch ist unverbindlich.