GitLab upgrade: come aggiornare self-managed con backup e stop

di Irene Valli redattrice IA 22 ottobre 2026, 17:45

Illustrazione 3D di una sala server con tecnici al lavoro e componenti hardware. — Immagine generata con IA

Se amministrate un’istanza GitLab self-managed su un solo nodo, installata con il pacchetto Linux o con Docker, dovete aggiornarla a una versione corretta. La falla è CVE-2026-110264. GitLab la classifica come critica, con CVSS 10.0, e permette a un utente non autenticato di eseguire codice sul server. Le versioni corrette sono uscite il 21 ottobre 2026 e sono 19.5.1, 19.4.3, 19.3.6, 19.2.9, 19.1.9, 19.0.10 e 18.11.13. Le trovate nell’avviso di sicurezza ufficiale. L’avviso non dice se la falla sia sfruttata attivamente. Dice però che GitLab ha pubblicato due regole per rilevare i tentativi di sfruttamento. GitLab.com è già aggiornato. Helm e Kubernetes restano fuori da questa guida. I comandi sono quelli della documentazione ufficiale, elencata in fondo.

GitLab upgrade plan analysis: 14.8.6 to 14.9.5Il video si carica da YouTube quando premi play

Cosa serve

Un’istanza GitLab self-managed su un solo nodo, installata con il pacchetto Linux (Ubuntu/Debian oppure RHEL/Oracle Linux/AlmaLinux 8/9), con Docker Engine o con Docker Compose.
Accesso al server con sudo e un account amministratore nell’interfaccia web.
Un sistema operativo supportato dalla versione di destinazione. Se aggiornate il sistema e cambia la versione di glibc, la pagina sull’aggiornamento del pacchetto Linux rimanda a una procedura specifica per PostgreSQL, che evita indici corrotti.
PostgreSQL, Redis e Gitaly in esecuzione.
Rsync installato. Con il pacchetto Linux c’è già.
Spazio su disco per l’archivio di backup e un posto fuori dal server dove copiare l’archivio, la configurazione e i segreti.

Valutate la modalità di manutenzione. Mettete in pausa pipeline e job CI/CD. Aggiornate GitLab Runner alla stessa versione di destinazione di GitLab. Se aggiornate mentre i Runner eseguono dei job, gli aggiornamenti dei log dei job non vanno a buon fine.

Controllare la versione installata e lo stato dei servizi

La versione installata dice se l’istanza è esposta e quale percorso seguire. Con il pacchetto Linux, questo comando raccoglie le informazioni sull’installazione e sul sistema:

sudo gitlab-rake gitlab:env:info

Cercate la sezione GitLab information e la riga Version. Nell’esempio della pagina dei Rake task di manutenzione la riga è questa:

Version: 15.5.5-ee

Nell’output di gitlab:env:info, il suffisso -ee identifica la Enterprise Edition; la Community Edition mostra di norma il numero senza suffisso -ce. Annotate numero ed edizione e confrontateli con le versioni vulnerabili dell’avviso. Poi controllate che i servizi siano attivi:

sudo gitlab-ctl status

Su Docker lanciate gli stessi comandi dentro il container. Scrivete docker exec, poi il nome del container e infine il comando senza sudo.

Fare il backup dei dati con la versione attuale

Fate il backup prima di cambiare versione. Controllate che non ci siano job Sidekiq in attesa o in esecuzione. Redis conserva questi job e non entra nel backup, quindi mettere in pausa le sole pipeline non basta per avere un backup coerente. Potrete ripristinare il backup solo su questa stessa versione e su questa stessa edizione (CE o EE). Con il pacchetto Linux:

sudo gitlab-backup create

Su Docker il backup si lancia dall’host, dentro il container. Scrivete docker exec -t, poi il nome del container e infine gitlab-backup create. Secondo la documentazione sul backup, l’output termina con la creazione dell’archivio:

Creating backup archive: <backup-id>_gitlab_backup.tar [DONE]

L’archivio contiene il database, i repository Git, gli oggetti LFS, gli artifact e i log CI/CD, le wiki, gli allegati e il registry salvato su file system. Restano fuori l’object storage, Redis, i file di /etc/gitlab e le chiavi TLS e SSH. Se usate l’object storage, attivate i backup presso il vostro fornitore.

Se avete abilitato il database dei metadati del Container Registry, controllate prima la versione installata. Le impostazioni per includerlo nel backup sono arrivate in GitLab 18.11. Da quella versione configurate in gitlab.rb il backup_role e le credenziali PostgreSQL per backup e ripristino (backup_registry_user, backup_registry_password, restore_registry_user, restore_registry_password). Poi eseguite sudo gitlab-ctl reconfigure prima del backup, come indica la documentazione per le installazioni su un solo nodo. Sulle versioni precedenti questa integrazione non esiste: dovete predisporre e verificare un backup separato del database dei metadati.

Prima di installare una nuova versione, il pacchetto Linux fa da solo un backup del database. La documentazione chiede comunque di tenere un backup completo e aggiornato.

Mettere al sicuro gitlab.rb e gitlab-secrets.json

Il backup standard non salva i file di configurazione. Il database contiene dati cifrati e la chiave per leggerli sta in gitlab-secrets.json. Se perdete quel file, GitLab non riesce più a decifrare quei dati. Dopo un ripristino senza segreti, gli utenti con autenticazione a due fattori perdono l’accesso e i GitLab Runner non riescono più ad autenticarsi.

Copiate fuori dal server almeno questi file:

con il pacchetto Linux, /etc/gitlab/gitlab-secrets.json e /etc/gitlab/gitlab.rb;
con Docker, il volume della configurazione, cioè /srv/gitlab/config se avete creato il container come indica la documentazione.

La documentazione suggerisce di salvare anche chiavi e certificati TLS (/etc/gitlab/ssl, /etc/gitlab/trusted-certs) e le chiavi host SSH. Non indica un comando per questa copia: usate il metodo che già usate per i file sensibili. Il file dei segreti può cambiare dopo un aggiornamento, quindi rifate la copia dopo ogni salto.

Calcolare il percorso con gli upgrade stop

La pagina Before you upgrade chiede di stabilire il percorso di aggiornamento dell’istanza, compresi gli upgrade stop obbligatori. Gli stop sono versioni intermedie da installare una dopo l’altra. Calcolate gli stop con l’Upgrade Path tool collegato da quella pagina. Leggete le note di aggiornamento di tutte le versioni tra quella installata e quella di destinazione e applicate i prerequisiti che vi riguardano. Se il percorso attraversa GitLab 18 e usate ancora git_data_dirs, migrate prima la configurazione Gitaly al formato storage: da GitLab 18.0 quell’impostazione non è più utilizzabile.

Calcolate il percorso fino alla versione che installerete davvero: la versione corretta esatta, se usate il comando per una versione specifica; l’ultima disponibile nel repository, se usate i comandi per l’ultima versione. Se il percorso prevede degli stop, non potete saltare direttamente all’ultima versione major.

Prima di ogni salto tutte le migrazioni in background devono essere concluse. La pagina sulle migrazioni in background indica strumenti diversi a seconda della versione installata:

prima di GitLab 18.5 non esistono Rake task per le migrazioni in background. Controllate dall’interfaccia oppure con la query della documentazione: entrate in psql con sudo gitlab-psql e interrogate la tabella batched_background_migrations. Se la query non restituisce righe, le migrazioni sono concluse;
da GitLab 18.5 a 18.8 si usa status, il primo comando qui sotto;
da GitLab 18.9 si usa sudo gitlab-rake gitlab:background_migrations:list, che elenca le migrazioni con stato e avanzamento;
da GitLab 19.5 c’è anche wait, che resta in attesa finché le migrazioni non sono concluse.

Da GitLab 18.5 a 18.8:

sudo gitlab-rake gitlab:background_migrations:status

Da GitLab 19.5:

sudo gitlab-rake gitlab:background_migrations:wait

Quando le migrazioni sono finite, il comando stampa questa riga ed esce con codice 0:

All batched background migrations have finished.

Se una migrazione è nello stato failed, wait esce con un errore, perché aspettare non basta a sbloccarla. Il comando non ha un timeout interno. Con qualsiasi versione potete controllare anche dall’interfaccia. Selezionate Admin in alto a destra, poi Monitoring > Background migrations nella barra laterale. Le schede Queued, Finalizing e Failed devono essere vuote.

Controllare la salute del database

Questi controlli dipendono dalla versione installata. Su versioni più vecchie di quelle indicate qui non sono disponibili: seguite le verifiche che prevede la documentazione della vostra versione.

Da GitLab 18.3: aprite Monitoring > Database diagnostics, eseguite Run schema check e attendete il risultato. Il controllo gira come job in background, quindi Sidekiq deve essere attivo. Se mancano tabelle, indici, chiavi esterne o sequenze, le migrazioni possono fallire. Non esiste uno strumento di riparazione automatico: contattate il supporto GitLab prima di aggiornare.
Da GitLab 19.2: c’è anche il controllo Search path. Può segnalare che più di uno schema nel search path contiene oggetti GitLab. In quel caso le migrazioni possono modificare gli oggetti sbagliati. Prima di aggiornare fate in modo che li contenga solo lo schema principale, chiedendo aiuto al supporto se serve.
Da GitLab 19.2, con PostgreSQL 17 o successivo: ricontrollate la sezione Vacuum information subito prima dell’aggiornamento. Il badge Anti-wraparound compare solo se il ruolo del database usato dal controllo può leggere l’attività degli altri backend, per esempio come membro di pg_monitor o con permessi equivalenti. Un pannello vuoto non esclude un vacuum anti-wraparound, e lo stesso vale per un valore Not available o per una versione non supportata: in questi casi fate controllare l’attività direttamente nel database. Se un vacuum anti-wraparound è in corso, non avviate l’aggiornamento e non interrompetelo: aspettate che finisca.

Aggiornare l’installazione da pacchetto Linux

Per ogni upgrade stop installate la versione esatta di quello stop. La pagina del pacchetto Linux riporta il comando per una versione specifica. Su Ubuntu/Debian si usa apt install con il nome del pacchetto seguito da versione ed edizione, nel formato <version>-ee.0 o <version>-ce.0. Su RHEL/AlmaLinux si usa dnf install con un nome come gitlab-ee-<version>-ee.0.el9 (o .el8). Al posto di <version> mettete il numero dello stop indicato dall’Upgrade Path tool. La stessa pagina spiega anche come scaricare il pacchetto in anticipo, per ridurre i tempi e verificare che sia disponibile.

Per l’ultimo salto avete due strade:

installare la versione corretta esatta indicata nell’avviso, con lo stesso comando per una versione specifica che avete usato per gli stop;
usare i comandi qui sotto, che installano l’ultima versione disponibile nel repository. Quella versione può essere più recente della versione corretta e richiedere altri stop. Usateli solo se l’Upgrade Path tool, calcolato fino all’ultima versione disponibile, non prevede altri stop dopo la versione che avete installato.

Scegliete il comando in base a distribuzione ed edizione (riga Version).

Ubuntu/Debian, Enterprise Edition:

sudo apt update && sudo apt install gitlab-ee

Ubuntu/Debian, Community Edition:

sudo apt update && sudo apt install gitlab-ce

RHEL/Oracle Linux/AlmaLinux 8/9, Enterprise Edition:

sudo dnf upgrade gitlab-ee

RHEL/Oracle Linux/AlmaLinux 8/9, Community Edition:

sudo dnf upgrade gitlab-ce

Aggiornare l’installazione Docker

Con Docker Engine si sostituisce il container. I dati restano nei volumi sotto $GITLAB_HOME. Prima di fermare il container, controllate di avere il backup e la copia della configurazione. Annotate le opzioni con cui l’avete creato: hostname, porte pubblicate, volumi, nome e policy di riavvio. Vi serviranno identiche dopo la rimozione, perché con volumi diversi la nuova istanza non trova i dati.

Fermate il container. Nella documentazione il container si chiama gitlab: se il vostro ha un altro nome, usate quello, cioè il valore di --name che avete dato alla creazione.

sudo docker stop gitlab

Rimuovete il container. Da questo momento l’istanza resta ferma finché non la ricreate.

sudo docker rm gitlab

Scaricate l’immagine della versione di destinazione. La pagina sull’aggiornamento Docker riporta due comandi: sudo docker pull gitlab/gitlab-ee:<version>-ee.0 per Enterprise Edition e sudo docker pull gitlab/gitlab-ce:<version>-ce.0 per Community Edition. Al posto di <version> mettete il numero dello stop. Poi controllate che sia definita la variabile con il percorso dei volumi:

echo $GITLAB_HOME

Il comando deve stampare la cartella che contiene config, logs e data. Se non stampa niente, definite la variabile prima di andare avanti. Il procedimento è nella pagina di installazione Docker, collegata da quella di aggiornamento.

Ricreate il container con le opzioni che avete annotato. Questo è l’esempio completo della documentazione, da adattare: sudo docker run --detach --hostname gitlab.example.com --publish 443:443 --publish 80:80 --publish 22:22 --name gitlab --restart always --volume $GITLAB_HOME/config:/etc/gitlab --volume $GITLAB_HOME/logs:/var/log/gitlab --volume $GITLAB_HOME/data:/var/opt/gitlab --shm-size 256m gitlab/gitlab-ee:<version>-ee.0. Al posto di gitlab.example.com mettete il vostro hostname e al posto di <version> la versione dello stop. Con la Community Edition l’immagine è gitlab/gitlab-ce:<version>-ce.0. Al primo avvio GitLab si riconfigura e si aggiorna da solo.

Con Docker Compose aprite docker-compose.yml e impostate il tag della versione dello stop. Poi scaricate l’immagine:

docker compose pull

Riavviate l’istanza:

docker compose up -d

Ripetete la procedura per ogni upgrade stop. Per l’ultimo salto usate il tag della versione corretta indicata nell’avviso. Potete usare anche una versione più recente, se il percorso calcolato fino a quella versione non prevede altri stop.

Verificare dopo ogni salto

Verificate ogni salto prima di passare allo stop successivo. La riga Version deve riportare la versione che vi aspettate:

sudo gitlab-rake gitlab:env:info

I servizi devono risultare attivi:

sudo gitlab-ctl status

Il controllo generale verifica GitLab Shell, Gitaly, Sidekiq e l’applicazione, e suggerisce come correggere i problemi che trova:

sudo gitlab-rake gitlab:check

Poi controllate le migrazioni in background con lo strumento adatto alla versione appena installata. Se il salto vi ha portato a una versione tra la 18.5 e la 18.8:

sudo gitlab-rake gitlab:background_migrations:status

Dalla 18.9 usate list, dalla 19.5 anche wait. Prima della 18.5 controllate dall’interfaccia o con la query in psql descritta sopra. In ogni caso le schede Queued, Finalizing e Failed di Background migrations devono essere vuote prima del salto successivo. Infine controllate che i valori cifrati del database si possano decifrare, con sudo gitlab-rake gitlab:doctor:secrets. La pagina Before you upgrade lo indica tra i controlli da fare subito prima e subito dopo l’aggiornamento.

Su Docker lanciate questi comandi dentro il container con docker exec. Poi controllate nell’interfaccia che:

gli utenti riescano ad accedere;
l’elenco dei progetti sia visibile e issue e merge request si aprano;
clone e push funzionino;
i Runner prendano i job.

Dopo l’ultimo salto riattivate pipeline e Runner. Se avete attivato la modalità di manutenzione, disattivatela.

Tornare indietro ripristinando il backup

Non esiste un downgrade semplice. Per tornare indietro si ripristina il backup fatto prima del salto. Il ripristino richiede un’istanza GitLab funzionante, con la stessa identica versione ed edizione del backup. L’istanza non deve contenere repository che possano entrare in conflitto: per un ripristino affidabile la documentazione raccomanda un’installazione nuova. Se l’istanza è già stata aggiornata, reinstallare la vecchia versione sopra non basta. Le indicazioni di rollback sono collegate dalla pagina Before you upgrade. Poi rimettete al loro posto gitlab.rb e gitlab-secrets.json ed eseguite gitlab-ctl reconfigure.

L’archivio deve stare nella cartella dei backup, che per impostazione predefinita è /var/opt/gitlab/backups, e deve appartenere all’utente git. Un file copiato con sudo appartiene a root, quindi va cambiato il proprietario. La documentazione usa due comandi: sudo cp 11493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar /var/opt/gitlab/backups/ e sudo chown git:git /var/opt/gitlab/backups/11493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar. Al posto del nome di esempio mettete il nome completo del vostro archivio. Nella cartella deve esserci spazio libero pari ad almeno tre volte la dimensione dell’archivio.

Fermate i processi collegati al database e lasciate attivo il resto:

sudo gitlab-ctl stop puma

sudo gitlab-ctl stop sidekiq

Controllate che siano fermi:

sudo gitlab-ctl status

Attenzione: il ripristino sovrascrive il database di GitLab e cancella i dati PostgreSQL attuali. Tutto quello che è stato creato dopo il backup va perso. Nel comando qui sotto, 11493107454_2018_04_25_10.6.4-ce è il nome di esempio della documentazione. Sostituitelo con il nome del vostro archivio in /var/opt/gitlab/backups, senza il suffisso _gitlab_backup.tar. La parte finale del nome riporta versione ed edizione: controllate che coincidano con quelle dell’istanza installata.

sudo gitlab-backup restore BACKUP=11493107454_2018_04_25_10.6.4-ce

Riconfigurate:

sudo gitlab-ctl reconfigure

Riavviate GitLab:

sudo gitlab-ctl start

Controllate l’installazione. Con SANITIZE=true l’output non riporta i nomi dei progetti:

sudo gitlab-rake gitlab:check SANITIZE=true

Verificate che i valori cifrati si decifrino con i segreti ripristinati:

sudo gitlab-rake gitlab:doctor:secrets

Su Docker eseguite i passaggi dentro il container con docker exec -it, e al posto di reconfigure e start riavviate il container. Secondo la pagina sul ripristino, le cartelle di destinazione devono essere vuote.

Se qualcosa va storto

Il ripristino si interrompe con «GitLab version mismatch». La versione installata è diversa da quella del backup. Il messaggio indica la versione che serve: installatela e ripetete il ripristino.
Errori «must be owner of extension» durante il ripristino. Messaggi come ERROR: must be owner of extension pg_trgm non bloccano nulla e il backup viene ripristinato lo stesso.
L’aggiornamento si ferma con «Expected batched background migration … to be marked as ‘finished’, but it is ‘active’». Una migrazione in background non era conclusa. Aspettate che finisca, oppure seguite le opzioni per completarla indicate nella pagina sulle migrazioni in background.
Migrazioni nello stato Failed. Vanno risolte prima di aggiornare. In Background migrations aprite la scheda Failed e selezionate la migrazione per leggere l’errore. Poi riprovatela con il pulsante di retry.
Dopo il ripristino gli utenti con 2FA non accedono e i Runner non si collegano. Manca gitlab-secrets.json, oppure non è quello giusto: rimettete la copia che avete salvato.

Se il problema resta, raccogliete errori e log con gitlabsos, disponibile per pacchetto Linux e Docker. Tornate all’ultima versione funzionante. Se il vostro piano lo prevede, contattate il supporto GitLab.

Documentazione di riferimento

Pagine ufficiali consultate il 22 ottobre 2026: