Migrazione da GitLab.com a GitLab self-hosted
Quando un team passa da GitLab.com a una propria istanza, il codice è solo una parte del lavoro. Anche issue, merge request, etichette, milestone e la loro cronologia devono essere trasferiti, possibilmente senza copiare nulla a mano.
GitLab dispone di un metodo integrato chiamato direct transfer. La tua istanza si collega a GitLab.com via HTTPS con un token di accesso personale e copia un gruppo insieme ai suoi progetti. L'importazione viene eseguita in background e, al termine, puoi verificare ogni elemento migrato.
Questa guida mostra la migrazione completa di un gruppo: preparare GitLab.com, avviare l'importazione, verificare il risultato e completare i passaggi che il direct transfer non copre. Tutti i passaggi sono stati testati su una migrazione reale da GitLab.com a GitLab 19.5 su Ubuntu 26.04.
Cosa serve prima della migrazione
Un'istanza GitLab self-hosted installata e funzionante. Se non ne hai ancora una, installala prima, vedi la guida Come installare GitLab su un server dedicato.
Accesso da amministratore alla tua istanza GitLab.
Il ruolo Owner nel gruppo che vuoi migrare su GitLab.com. La pagina di importazione elenca solo i gruppi in cui sei Owner.
Accesso HTTPS in uscita dal tuo server a https://gitlab.com.
Spazio libero su disco sufficiente sul server per tutti i repository che migri e spazio libero in /tmp: GitLab vi estrae gli archivi temporanei della migrazione.
GitLab.com esegue sempre una versione più recente di un'istanza self-hosted. Nel nostro test questo non ha impedito la migrazione.
In tutta la guida, sostituisci gitlab.example.com con il dominio della tua istanza.
Cosa viene migrato
Il direct transfer trasferisce:
- il gruppo e i suoi progetti;
- i repository con tutti i branch e la cronologia dei commit, gli hash dei commit restano invariati;
- issue e merge request con i numeri originali;
- etichette, milestone e cronologia delle attività;
- le date di creazione originali.
I contributi importati e alcune appartenenze vengono prima collegati a utenti segnaposto (placeholder). Dopo l'importazione li riassegni ad account reali della tua istanza.
Il direct transfer non migra:
- le variabili CI/CD, le variabili delle pianificazioni delle pipeline e i trigger delle pipeline;
- le deploy key e i deploy token;
- le immagini del container registry e il package registry;
- i log e gli artefatti dei job CI/CD;
- i webhook;
- gli ambienti e i feature flag;
- le regole di approvazione delle merge request e le issue collegate;
- i mirror remoti.
Le pipeline vengono migrate come record con il loro stato, ma senza log dei job e artefatti.
Pianifica come ripristinerai questi elementi prima di iniziare. Le variabili CI/CD, le deploy key e i deploy token contengono spesso password e chiavi API, quindi li ricrei manualmente dopo l'importazione. Le immagini dei container e i pacchetti non vengono copiati: caricali di nuovo sulla tua istanza o ricostruiscili con la CI.
Preparare il tuo account GitLab.com
Rendi pubblica la tua email. Su GitLab.com, seleziona il tuo avatar nell'angolo in alto a destra e poi Edit profile. In Public email, seleziona il tuo indirizzo email e seleziona Update profile settings in fondo alla pagina.
Crea un token di accesso personale. La tua istanza usa questo token per leggere i tuoi dati su GitLab.com. Nel menu a sinistra del profilo, vai su Access > Personal access tokens.
Seleziona Generate token e poi Legacy token.
Compila il modulo:
- Token name: un nome qualsiasi, ad esempio
migration. - Expiration date: per la migrazione bastano pochi giorni.
- Select scopes: seleziona
api. Non confonderlo conread_api.
Seleziona Generate token. Copia il token, che inizia con glpat-, e salvalo in un posto sicuro. GitLab.com lo mostra una sola volta.
Non inviare il token in chat o via email. Chiunque lo possieda ottiene pieno accesso API al tuo account GitLab.com finché il token non scade o non viene revocato.
Abilitare il direct transfer sulla tua istanza
Accedi alla tua istanza GitLab come amministratore. Seleziona Admin nell'angolo in alto a destra, vai su Settings > General ed espandi Import and export settings. In Allow migrating GitLab groups and projects by direct transfer, seleziona la casella Enabled e seleziona Save changes.
Nella stessa sezione, controlla due impostazioni che influiscono sulla riassegnazione degli utenti dopo l'importazione:
- Allow contribution mapping to administrators: se è attiva, puoi riassegnare i contributi anche ad account amministratore;
- Skip confirmation when administrators reassign placeholder users: se è attiva, i contributi vengono riassegnati subito, senza l'approvazione dell'utente.
Collegare la tua istanza a GitLab.com
Seleziona Create new (l'icona del più) nella barra superiore, poi New group > Import group.
Compila il modulo di connessione:
- GitLab source instance base URL:
https://gitlab.com - Personal access token: il token che hai creato su GitLab.com.
Seleziona Connect instance.
Si apre la pagina Import groups by direct transfer con l'elenco dei tuoi gruppi su GitLab.com.
Avviare l'importazione
Trova il gruppo nell'elenco. In Path of the new group, apri Select parent group e scegli dove collocare il gruppo:
- No parent crea un gruppo di primo livello, come su GitLab.com;
- un gruppo esistente sulla tua istanza importa il gruppo al suo interno come sottogruppo. Se il gruppo padre è privato, i gruppi e i progetti pubblici di GitLab.com diventano privati dopo l'importazione.
Questa scelta è obbligatoria. Finché non selezioni un gruppo padre, GitLab mostra Select a parent group e non avvia l'importazione.
Controlla il percorso del nuovo gruppo, per impostazione predefinita coincide con il nome su GitLab.com. Lascia selezionata Import user memberships per trasferire i membri del gruppo.
Non modificare il gruppo e i suoi progetti su GitLab.com dopo l'avvio dell'importazione. Le modifiche fatte durante la migrazione potrebbero non arrivare alla tua istanza. Chiedi al team di smettere di fare push di codice e di modificare le issue fino al termine dell'importazione.
Seleziona Import with projects nella riga del gruppo. Lo stato cambia in Importing.
Se il pulsante Import with projects non c'è, controlla Default minimum role required to create projects in Admin > Settings > General > Visibility and access controls. Se è impostato su No one, GitLab non può importare i progetti.
L'importazione viene eseguita in background, quindi puoi chiudere la pagina. Il tempo dipende dal numero e dalle dimensioni dei progetti: nel nostro test, un gruppo con due piccoli progetti ha richiesto circa due minuti.
Verificare il risultato
Quando l'importazione termina, lo stato cambia in Complete.
Se lo stato è Failed o Partially completed, seleziona Show errors per vedere quali elementi non sono stati importati. Puoi ripetere una migrazione fallita o parziale dalla stessa pagina o tramite API.
Seleziona Migration details. La pagina Migration history mostra il gruppo e ogni progetto con il proprio stato.
Apri il gruppo importato e controlla il suo contenuto.
Progetti. Tutti i progetti del gruppo devono essere nell'elenco.
Issue e merge request. Apri Work items e Merge requests nel menu del gruppo. Numeri, etichette e milestone vengono mantenuti e gli elementi importati hanno il badge Imported.
Repository. In un progetto, vai su Code > Branches. Controlla che ci siano tutti i branch attesi e che i loro ultimi commit coincidano con il repository di origine.
Gli autori di issue e merge request sono mostrati come Placeholder users, ad esempio Placeholder John Smith. È normale, li riassegnerai più avanti in questa guida.
Se una merge request mostra Cannot be merged automatically, aprila e controlla la scheda Changes. Se non mostra modifiche, la merge request non aveva commit nemmeno su GitLab.com, quindi non c'è nulla da unire. Non è un errore di migrazione.
Ricreare le variabili CI/CD
Su GitLab.com, apri il progetto e vai su Settings > CI/CD, espandi Variables e annota ogni variabile con le sue opzioni, ad esempio Protected e Masked.
Sulla tua istanza, apri lo stesso progetto e la stessa sezione. L'elenco delle variabili del progetto è vuoto.
Seleziona Add variable e crea ogni variabile con la stessa chiave, lo stesso valore e le stesse opzioni. Ripeti l'operazione per le variabili di gruppo, se le usi.
Le pianificazioni delle pipeline vengono migrate senza le loro variabili. Se le tue pianificazioni usano variabili, apri Build > Pipeline schedules nel progetto e aggiungile a ogni pianificazione.
Riassegnare gli utenti segnaposto
Durante l'importazione, GitLab crea utenti segnaposto per gli autori dei contributi e per i membri importati da GitLab.com. Per collegare le loro issue, merge request e commenti ad account reali, riassegna i segnaposto. Crea prima sull'istanza gli account del tuo team, in modo da avere qualcuno a cui riassegnare.
Apri il gruppo di primo livello, cioè il gruppo importato stesso o il suo padre se l'hai importato come sottogruppo, vai su Manage > Members e seleziona la scheda Placeholders. Ti serve il ruolo Owner in questo gruppo. L'elenco Awaiting reassignment mostra tutti gli utenti segnaposto.
Nella riga di un segnaposto, apri Select user e scegli l'account sulla tua istanza. Verifica che nella riga giusta sia selezionato l'account giusto, poi seleziona Reassign e Confirm reassignment.
La riassegnazione non può essere annullata. Una scelta sbagliata attribuisce i contributi e l'accesso di una persona a un altro utente, quindi controlla ogni riga prima di confermare.
Lo stato cambia in Reassigning. Dopo un minuto, aggiorna la pagina: il segnaposto passa alla scheda Reassigned.
Ora l'issue mostra l'account reale come autore e la data di creazione originale viene mantenuta.
Se Skip confirmation when administrators reassign placeholder users è attiva, come sulla nostra istanza di test, i contributi vengono riassegnati subito. Se è disattivata, l'utente selezionato deve prima accettare la riassegnazione.
Anche gli account di servizio di GitLab.com, ad esempio Duo Code Review, arrivano come segnaposto. Non hanno corrispondenza sulla tua istanza: lasciali così o seleziona Do not reassign. Per molti utenti, usa Reassign with CSV file nella stessa scheda.
Completare la migrazione
Revoca il token. Su GitLab.com, vai su Access > Personal access tokens e seleziona Revoke accanto al token di migrazione.
Aggiorna l'indirizzo remoto sui computer degli sviluppatori. In ogni copia locale di un repository, punta Git alla tua istanza:
git remote set-url origin [email protected]:group/project.git
Sostituisci group/project con il percorso del progetto sulla tua istanza.
Configura di nuovo integrazioni e automazioni. Webhook, deploy key, deploy token e trigger delle pipeline non vengono migrati, quindi ricreali sulla tua istanza. Registra i runner CI/CD sulla tua istanza. Ricollega i servizi esterni, come le notifiche di chat o gli issue tracker, nelle impostazioni di ogni progetto.
Esegui nuove pipeline sulle merge request importate. Le pipeline importate mantengono il loro stato originale e possono soddisfare Pipelines must succeed senza essere eseguite di nuovo. Prima di unire una merge request importata, esegui per essa una nuova pipeline sulla tua istanza.
Chiudi la vecchia copia. Quando tutto funziona sulla tua istanza, archivia o elimina il gruppo su GitLab.com in modo che nessuno continui a lavorarci.
Per scegliere un server per la tua istanza GitLab, vedi la pagina Server dedicati per GitLab.
