Migracja z GitLab.com do samodzielnie hostowanego GitLab

Gdy zespół przenosi się z GitLab.com na własną instancję, kod to tylko część pracy. Zgłoszenia (issues), merge requesty, etykiety, kamienie milowe i ich historia również muszą zostać przeniesione, najlepiej bez ręcznego kopiowania.

GitLab ma do tego wbudowaną metodę o nazwie direct transfer. Twoja instancja łączy się z GitLab.com przez HTTPS za pomocą osobistego tokena dostępu i kopiuje grupę wraz z jej projektami. Import działa w tle, a po jego zakończeniu możesz sprawdzić każdy przeniesiony element.

Ta instrukcja pokazuje pełną migrację jednej grupy: przygotowanie GitLab.com, uruchomienie importu, sprawdzenie wyniku i dokończenie kroków, których direct transfer nie obejmuje. Wszystkie kroki przetestowano podczas rzeczywistej migracji z GitLab.com na GitLab 19.5 w Ubuntu 26.04.

Czego potrzebujesz przed migracją

Zainstalowana i działająca instancja GitLab typu self-hosted. Jeśli jeszcze jej nie masz, najpierw ją zainstaluj, zobacz instrukcję Jak zainstalować GitLab na serwerze dedykowanym.

Dostęp administratora do Twojej instancji GitLab.

Rola Owner w grupie, którą chcesz przenieść na GitLab.com. Strona importu wyświetla tylko grupy, w których jesteś Owner.

Wychodzący dostęp HTTPS z Twojego serwera do https://gitlab.com.

Wystarczająca ilość wolnego miejsca na dysku serwera dla wszystkich migrowanych repozytoriów oraz wolne miejsce w /tmp: GitLab rozpakowuje tam tymczasowe archiwa migracji.

W całej instrukcji zamień gitlab.example.com na domenę swojej instancji.

Co jest migrowane

Direct transfer przenosi:

• grupę i jej projekty;
• repozytoria ze wszystkimi gałęziami i historią commitów, hasze commitów pozostają takie same;
• zgłoszenia i merge requesty z ich oryginalnymi numerami;
• etykiety, kamienie milowe i historię aktywności;
• oryginalne daty utworzenia.

Zaimportowane wkłady i niektóre członkostwa są najpierw przypisywane do użytkowników zastępczych (placeholder). Po imporcie przypisujesz je ponownie do prawdziwych kont na swojej instancji.

Direct transfer nie przenosi:

• zmiennych CI/CD, zmiennych harmonogramów pipeline'ów i triggerów pipeline'ów;
• deploy keys i deploy tokenów;
• obrazów container registry i package registry;
• logów i artefaktów jobów CI/CD;
• webhooków;
• środowisk i feature flag;
• reguł zatwierdzania merge requestów i powiązanych zgłoszeń;
• zdalnych mirrorów.

Pipeline'y są migrowane jako rekordy z ich statusami, ale bez logów jobów i artefaktów.

Przygotowanie konta GitLab.com

Upublicznij swój adres e-mail. Na GitLab.com wybierz swój awatar w prawym górnym rogu, a następnie Edit profile. W polu Public email wybierz swój adres e-mail i wybierz Update profile settings na dole strony.

Utwórz osobisty token dostępu. Twoja instancja używa tego tokena do odczytu Twoich danych na GitLab.com. W lewym menu profilu przejdź do Access > Personal access tokens.

Wybierz Generate token, a następnie Legacy token.

Wypełnij formularz:

• Token name: dowolna nazwa, na przykład migration.
• Expiration date: na czas migracji wystarczy kilka dni.
• Select scopes: wybierz api. Nie myl go z read_api.

Wybierz Generate token. Skopiuj token, zaczyna się od glpat-, i zapisz go w bezpiecznym miejscu. GitLab.com pokazuje go tylko raz.

Włączenie direct transfer na Twojej instancji

Zaloguj się do swojej instancji GitLab jako administrator. Wybierz Admin w prawym górnym rogu, przejdź do Settings > General i rozwiń Import and export settings. W sekcji Allow migrating GitLab groups and projects by direct transfer zaznacz pole Enabled i wybierz Save changes.

W tej samej sekcji sprawdź dwa ustawienia, które wpływają na ponowne przypisanie użytkowników po imporcie:

• Allow contribution mapping to administrators: gdy jest włączone, możesz przypisywać wkłady także do kont administratorów;
• Skip confirmation when administrators reassign placeholder users: gdy jest włączone, wkłady są przypisywane natychmiast, bez zatwierdzenia przez użytkownika.

Połączenie instancji z GitLab.com

Wybierz Create new (ikona plusa) na górnym pasku, a następnie New group > Import group.

Wypełnij formularz połączenia:

• GitLab source instance base URL: https://gitlab.com
• Personal access token: token utworzony na GitLab.com.

Wybierz Connect instance.

Otworzy się strona Import groups by direct transfer z listą Twoich grup na GitLab.com.

Uruchomienie importu

Znajdź grupę na liście. W polu Path of the new group otwórz Select parent group i wybierz, gdzie umieścić grupę:

• No parent tworzy grupę najwyższego poziomu, tak jak na GitLab.com;
• istniejąca grupa na Twojej instancji importuje grupę do siebie jako podgrupę. Jeśli grupa nadrzędna jest prywatna, publiczne grupy i projekty z GitLab.com po imporcie staną się prywatne.

Sprawdź ścieżkę nowej grupy, domyślnie jest zgodna z nazwą na GitLab.com. Pozostaw zaznaczone Import user memberships, aby członkowie grupy zostali przeniesieni.

Wybierz Import with projects w wierszu grupy. Status zmieni się na Importing.

Import działa w tle, więc możesz zamknąć stronę. Czas zależy od liczby i rozmiaru projektów: w naszym teście grupa z dwoma małymi projektami zajęła około dwóch minut.

Sprawdzenie wyniku

Gdy import się zakończy, status zmieni się na Complete.

Jeśli status to Failed lub Partially completed, wybierz Show errors, aby zobaczyć, które elementy nie zostały zaimportowane. Nieudaną lub częściową migrację możesz powtórzyć z tej samej strony lub przez API.

Wybierz Migration details. Strona Migration history pokazuje grupę i każdy projekt z jego własnym statusem.

Otwórz zaimportowaną grupę i sprawdź jej zawartość.

Projekty. Wszystkie projekty grupy muszą być na liście.

Zgłoszenia i merge requesty. Otwórz Work items i Merge requests w menu grupy. Numery, etykiety i kamienie milowe są zachowane, a zaimportowane elementy mają znaczek Imported.

Repozytorium. W projekcie przejdź do Code > Branches. Sprawdź, czy są wszystkie oczekiwane gałęzie i czy ich najnowsze commity zgadzają się z repozytorium źródłowym.

Jeśli merge request pokazuje Cannot be merged automatically, otwórz go i sprawdź kartę Changes. Jeśli nie ma w niej zmian, merge request nie miał commitów także na GitLab.com, więc nie ma czego scalać. To nie jest błąd migracji.

Odtworzenie zmiennych CI/CD

Na GitLab.com otwórz projekt i przejdź do Settings > CI/CD, rozwiń Variables i zanotuj każdą zmienną wraz z jej opcjami, na przykład Protected i Masked.

Na swojej instancji otwórz ten sam projekt i tę samą sekcję. Lista zmiennych projektu jest pusta.

Wybierz Add variable i utwórz każdą zmienną z tym samym kluczem, wartością i opcjami. Powtórz to dla zmiennych grupy, jeśli z nich korzystasz.

Harmonogramy pipeline'ów są migrowane bez swoich zmiennych. Jeśli Twoje harmonogramy używają zmiennych, otwórz w projekcie Build > Pipeline schedules i dodaj je do każdego harmonogramu.

Ponowne przypisanie użytkowników zastępczych

Podczas importu GitLab tworzy użytkowników zastępczych dla autorów wkładów i dla zaimportowanych członków z GitLab.com. Aby powiązać ich zgłoszenia, merge requesty i komentarze z prawdziwymi kontami, przypisz użytkowników zastępczych ponownie. Najpierw utwórz na instancji konta swojego zespołu, aby było komu przypisywać.

Otwórz grupę najwyższego poziomu, czyli samą zaimportowaną grupę lub jej grupę nadrzędną, jeśli importowałeś ją jako podgrupę, przejdź do Manage > Members i wybierz kartę Placeholders. Potrzebujesz roli Owner w tej grupie. Lista Awaiting reassignment pokazuje wszystkich użytkowników zastępczych.

W wierszu użytkownika zastępczego otwórz Select user i wybierz konto na swojej instancji. Sprawdź, czy w odpowiednim wierszu wybrano właściwe konto, a następnie wybierz Reassign i Confirm reassignment.

Status zmieni się na Reassigning. Po minucie odśwież stronę: użytkownik zastępczy przeniesie się na kartę Reassigned.

Zgłoszenie pokazuje teraz prawdziwe konto jako autora, a oryginalna data utworzenia jest zachowana.

Konta serwisowe GitLab.com, na przykład Duo Code Review, również trafiają jako użytkownicy zastępczy. Nie mają odpowiednika na Twojej instancji: zostaw je bez zmian lub wybierz Do not reassign. Dla wielu użytkowników użyj Reassign with CSV file na tej samej karcie.

Zakończenie migracji

Unieważnij token. Na GitLab.com przejdź do Access > Personal access tokens i wybierz Revoke obok tokena migracji.

Zaktualizuj adres zdalny na komputerach deweloperów. W każdej lokalnej kopii repozytorium wskaż Gitowi swoją instancję:

git remote set-url origin [email protected]:group/project.git

Zamień group/project na ścieżkę projektu na swojej instancji.

Skonfiguruj ponownie integracje i automatyzację. Webhooki, deploy keys, deploy tokeny i triggery pipeline'ów nie są migrowane, więc utwórz je na swojej instancji od nowa. Zarejestruj runnery CI/CD na swojej instancji. Połącz ponownie usługi zewnętrzne, takie jak powiadomienia czatu lub systemy zgłoszeń, w ustawieniach każdego projektu.

Uruchom nowe pipeline'y dla zaimportowanych merge requestów. Zaimportowane pipeline'y zachowują swój oryginalny status i mogą spełniać warunek Pipelines must succeed bez ponownego uruchomienia. Przed scaleniem zaimportowanego merge requesta uruchom dla niego nowy pipeline na swojej instancji.

Zamknij starą kopię. Gdy wszystko działa na Twojej instancji, zarchiwizuj lub usuń grupę na GitLab.com, aby nikt nie kontynuował tam pracy.

Aby wybrać serwer dla swojej instancji GitLab, zobacz stronę Serwery dedykowane dla GitLab.