Migration de GitLab.com vers un GitLab auto-hébergé
Lorsqu'une équipe quitte GitLab.com pour sa propre instance, le code n'est qu'une partie du travail. Les tickets (issues), les merge requests, les étiquettes, les jalons et leur historique doivent aussi être transférés, de préférence sans copie manuelle.
GitLab dispose pour cela d'une méthode intégrée appelée direct transfer. Votre instance se connecte à GitLab.com en HTTPS avec un jeton d'accès personnel et copie un groupe avec ses projets. L'import s'exécute en arrière-plan et, une fois terminé, vous pouvez vérifier chaque élément migré.
Ce guide présente la migration complète d'un groupe : préparer GitLab.com, lancer l'import, vérifier le résultat et terminer les étapes que direct transfer ne couvre pas. Toutes les étapes ont été testées lors d'une migration réelle de GitLab.com vers GitLab 19.5 sous Ubuntu 26.04.
Ce qu'il vous faut avant la migration
Une instance GitLab auto-hébergée installée et en fonctionnement. Si vous n'en avez pas encore, installez-la d'abord, voir le guide Comment installer GitLab sur un serveur dédié.
Un accès administrateur à votre instance GitLab.
Le rôle Owner dans le groupe que vous souhaitez migrer sur GitLab.com. La page d'import ne liste que les groupes dont vous êtes Owner.
Un accès HTTPS sortant depuis votre serveur vers https://gitlab.com.
Suffisamment d'espace disque libre sur le serveur pour tous les dépôts que vous migrez, ainsi que de l'espace libre dans /tmp : GitLab y décompresse les archives temporaires de migration.
GitLab.com exécute toujours une version plus récente qu'une instance auto-hébergée. Lors de notre test, cela n'a pas empêché la migration.
Tout au long de ce guide, remplacez gitlab.example.com par le domaine de votre instance.
Ce qui est migré
Direct transfer déplace :
- le groupe et ses projets ;
- les dépôts avec toutes les branches et l'historique des commits, les hachages des commits restent identiques ;
- les tickets et les merge requests avec leurs numéros d'origine ;
- les étiquettes, les jalons et l'historique d'activité ;
- les dates de création d'origine.
Les contributions importées et certaines appartenances sont d'abord rattachées à des utilisateurs substituts (placeholder). Après l'import, vous les réaffectez à de vrais comptes de votre instance.
Direct transfer ne migre pas :
- les variables CI/CD, les variables des planifications de pipelines et les déclencheurs de pipelines ;
- les deploy keys et les deploy tokens ;
- les images du container registry et le package registry ;
- les journaux et les artefacts des jobs CI/CD ;
- les webhooks ;
- les environnements et les feature flags ;
- les règles d'approbation des merge requests et les tickets liés ;
- les miroirs distants.
Les pipelines sont migrés sous forme d'enregistrements avec leur statut, mais sans journaux de jobs ni artefacts.
Prévoyez avant de commencer comment vous restaurerez ces éléments. Les variables CI/CD, les deploy keys et les deploy tokens contiennent souvent des mots de passe et des clés d'API, vous les recréez donc manuellement après l'import. Les images de conteneurs et les paquets ne sont pas copiés : poussez-les à nouveau vers votre instance ou reconstruisez-les avec la CI.
Préparer votre compte GitLab.com
Rendez votre e-mail public. Sur GitLab.com, sélectionnez votre avatar dans le coin supérieur droit, puis Edit profile. Dans Public email, sélectionnez votre adresse e-mail et sélectionnez Update profile settings en bas de la page.
Créez un jeton d'accès personnel. Votre instance utilise ce jeton pour lire vos données sur GitLab.com. Dans le menu de gauche de votre profil, allez dans Access > Personal access tokens.
Sélectionnez Generate token, puis Legacy token.
Remplissez le formulaire :
- Token name : un nom quelconque, par exemple
migration. - Expiration date : quelques jours suffisent pour la migration.
- Select scopes : sélectionnez
api. Ne le confondez pas avecread_api.
Sélectionnez Generate token. Copiez le jeton, qui commence par glpat-, et enregistrez-le dans un endroit sûr. GitLab.com ne l'affiche qu'une seule fois.
N'envoyez pas le jeton dans des discussions ou des e-mails. Quiconque le possède obtient un accès complet à l'API de votre compte GitLab.com jusqu'à son expiration ou sa révocation.
Activer direct transfer sur votre instance
Connectez-vous à votre instance GitLab en tant qu'administrateur. Sélectionnez Admin dans le coin supérieur droit, allez dans Settings > General et développez Import and export settings. Sous Allow migrating GitLab groups and projects by direct transfer, cochez la case Enabled et sélectionnez Save changes.
Dans la même section, vérifiez deux paramètres qui influent sur la réaffectation des utilisateurs après l'import :
- Allow contribution mapping to administrators : lorsqu'il est activé, vous pouvez aussi réaffecter des contributions à des comptes administrateur ;
- Skip confirmation when administrators reassign placeholder users : lorsqu'il est activé, les contributions sont réaffectées immédiatement, sans l'approbation de l'utilisateur.
Connecter votre instance à GitLab.com
Sélectionnez Create new (l'icône plus) dans la barre supérieure, puis New group > Import group.
Remplissez le formulaire de connexion :
- GitLab source instance base URL :
https://gitlab.com - Personal access token : le jeton que vous avez créé sur GitLab.com.
Sélectionnez Connect instance.
La page Import groups by direct transfer s'ouvre avec la liste de vos groupes sur GitLab.com.
Lancer l'import
Trouvez le groupe dans la liste. Dans Path of the new group, ouvrez Select parent group et choisissez où placer le groupe :
- No parent crée un groupe de premier niveau, comme sur GitLab.com ;
- un groupe existant sur votre instance importe le groupe en son sein comme sous-groupe. Si le groupe parent est privé, les groupes et projets publics de GitLab.com deviennent privés après l'import.
Ce choix est obligatoire. Tant que vous ne sélectionnez pas de groupe parent, GitLab affiche Select a parent group et ne lance pas l'import.
Vérifiez le chemin du nouveau groupe, par défaut il correspond au nom sur GitLab.com. Laissez Import user memberships sélectionné pour que les membres du groupe soient transférés.
Ne modifiez pas le groupe ni ses projets sur GitLab.com une fois l'import lancé. Les modifications effectuées pendant la migration peuvent ne pas parvenir à votre instance. Demandez à l'équipe de cesser de pousser du code et de modifier des tickets jusqu'à la fin de l'import.
Sélectionnez Import with projects dans la ligne du groupe. Le statut passe à Importing.
S'il n'y a pas de bouton Import with projects, vérifiez Default minimum role required to create projects dans Admin > Settings > General > Visibility and access controls. Lorsqu'il est défini sur No one, GitLab ne peut pas importer de projets.
L'import s'exécute en arrière-plan, vous pouvez donc fermer la page. La durée dépend du nombre et de la taille des projets : lors de notre test, un groupe de deux petits projets a pris environ deux minutes.
Vérifier le résultat
Lorsque l'import est terminé, le statut passe à Complete.
Si le statut est Failed ou Partially completed, sélectionnez Show errors pour voir quels éléments n'ont pas été importés. Vous pouvez relancer une migration échouée ou partielle depuis la même page ou via l'API.
Sélectionnez Migration details. La page Migration history affiche le groupe et chaque projet avec son propre statut.
Ouvrez le groupe importé et vérifiez son contenu.
Projets. Tous les projets du groupe doivent figurer dans la liste.
Tickets et merge requests. Ouvrez Work items et Merge requests dans le menu du groupe. Les numéros, les étiquettes et les jalons sont conservés, et les éléments importés portent le badge Imported.
Dépôt. Dans un projet, allez dans Code > Branches. Vérifiez que toutes les branches attendues sont présentes et que leurs derniers commits correspondent au dépôt source.
Les auteurs des tickets et des merge requests apparaissent comme Placeholder users, par exemple Placeholder John Smith. C'est normal, vous les réaffecterez plus loin dans ce guide.
Si une merge request affiche Cannot be merged automatically, ouvrez-la et vérifiez l'onglet Changes. S'il n'affiche aucune modification, la merge request n'avait pas non plus de commits sur GitLab.com, il n'y a donc rien à fusionner. Ce n'est pas une erreur de migration.
Recréer les variables CI/CD
Sur GitLab.com, ouvrez le projet et allez dans Settings > CI/CD, développez Variables et notez chaque variable avec ses options, par exemple Protected et Masked.
Sur votre instance, ouvrez le même projet et la même section. La liste des variables du projet est vide.
Sélectionnez Add variable et créez chaque variable avec la même clé, la même valeur et les mêmes options. Répétez l'opération pour les variables de groupe si vous en utilisez.
Les planifications de pipelines sont migrées sans leurs variables. Si vos planifications utilisent des variables, ouvrez Build > Pipeline schedules dans le projet et ajoutez-les à chaque planification.
Réaffecter les utilisateurs substituts
Pendant l'import, GitLab crée des utilisateurs substituts pour les auteurs de contributions et pour les membres importés de GitLab.com. Pour rattacher leurs tickets, merge requests et commentaires à de vrais comptes, réaffectez les substituts. Créez d'abord les comptes de votre équipe sur l'instance, afin d'avoir quelqu'un à qui réaffecter.
Ouvrez le groupe de premier niveau, c'est-à-dire le groupe importé lui-même ou son parent si vous l'avez importé comme sous-groupe, allez dans Manage > Members, puis sélectionnez l'onglet Placeholders. Vous avez besoin du rôle Owner dans ce groupe. La liste Awaiting reassignment affiche tous les utilisateurs substituts.
Dans la ligne d'un substitut, ouvrez Select user et choisissez le compte de votre instance. Vérifiez que le bon compte est sélectionné dans la bonne ligne, puis sélectionnez Reassign et Confirm reassignment.
La réaffectation est irréversible. Un mauvais choix donne les contributions et l'accès d'une personne à un autre utilisateur, vérifiez donc chaque ligne avant de confirmer.
Le statut passe à Reassigning. Après une minute, actualisez la page : le substitut passe dans l'onglet Reassigned.
Le ticket affiche désormais le vrai compte comme auteur, et la date de création d'origine est conservée.
Si Skip confirmation when administrators reassign placeholder users est activé, comme sur notre instance de test, les contributions sont réaffectées immédiatement. S'il est désactivé, l'utilisateur sélectionné doit d'abord accepter la réaffectation.
Les comptes de service de GitLab.com, par exemple Duo Code Review, arrivent aussi comme substituts. Ils n'ont pas d'équivalent sur votre instance : laissez-les tels quels ou sélectionnez Do not reassign. Pour de nombreux utilisateurs, utilisez Reassign with CSV file dans le même onglet.
Terminer la migration
Révoquez le jeton. Sur GitLab.com, allez dans Access > Personal access tokens et sélectionnez Revoke à côté du jeton de migration.
Mettez à jour l'adresse distante sur les postes des développeurs. Dans chaque copie locale d'un dépôt, faites pointer Git vers votre instance :
git remote set-url origin [email protected]:group/project.git
Remplacez group/project par le chemin du projet sur votre instance.
Reconfigurez les intégrations et l'automatisation. Les webhooks, les deploy keys, les deploy tokens et les déclencheurs de pipelines ne sont pas migrés, recréez-les donc sur votre instance. Enregistrez les runners CI/CD auprès de votre instance. Reconnectez les services externes, tels que les notifications de messagerie ou les outils de suivi de tickets, dans les paramètres de chaque projet.
Lancez de nouveaux pipelines sur les merge requests importées. Les pipelines importés conservent leur statut d'origine et peuvent satisfaire Pipelines must succeed sans être réexécutés. Avant de fusionner une merge request importée, lancez-lui un nouveau pipeline sur votre instance.
Fermez l'ancienne copie. Lorsque tout fonctionne sur votre instance, archivez ou supprimez le groupe sur GitLab.com afin que personne ne continue d'y travailler.
Pour choisir un serveur pour votre instance GitLab, consultez la page Serveurs dédiés pour GitLab.
