Migracija s GitLab.com na samostalno hostirani GitLab
Kada tim prelazi s GitLab.com na vlastitu instancu, kod je samo dio posla. Zadaci (issues), zahtjevi za spajanje (merge requests), oznake, prekretnice i njihova povijest također se moraju prenijeti, po mogućnosti bez ručnog kopiranja.
GitLab za to ima ugrađenu metodu zvanu direct transfer. Vaša se instanca povezuje s GitLab.com putem HTTPS-a pomoću osobnog pristupnog tokena i kopira grupu zajedno s njezinim projektima. Uvoz se izvodi u pozadini, a po završetku možete provjeriti svaki preneseni element.
Ove upute pokazuju potpunu migraciju jedne grupe: pripremu GitLab.com, pokretanje uvoza, provjeru rezultata i dovršetak koraka koje direct transfer ne pokriva. Svi su koraci testirani na stvarnoj migraciji s GitLab.com na GitLab 19.5 na Ubuntuu 26.04.
Što trebate prije migracije
Samostalno hostiranu GitLab instancu koja je instalirana i radi. Ako je još nemate, prvo je instalirajte, pogledajte upute Kako instalirati GitLab na namjenski poslužitelj.
Administratorski pristup svojoj GitLab instanci.
Ulogu Owner u grupi koju želite migrirati na GitLab.com. Stranica za uvoz navodi samo grupe u kojima ste Owner.
Odlazni HTTPS pristup s vašeg poslužitelja na https://gitlab.com.
Dovoljno slobodnog prostora na disku poslužitelja za sve repozitorije koje migrirate te slobodan prostor u /tmp: GitLab ondje raspakirava privremene arhive migracije.
GitLab.com uvijek radi na novijoj verziji od samostalno hostirane instance. U našem testu to nije spriječilo migraciju.
U ovim uputama svugdje zamijenite gitlab.example.com domenom svoje instance.
Što se migrira
Direct transfer prenosi:
- grupu i njezine projekte;
- repozitorije sa svim granama i poviješću commitova, hashevi commitova ostaju isti;
- zadatke i zahtjeve za spajanje s izvornim brojevima;
- oznake, prekretnice i povijest aktivnosti;
- izvorne datume izrade.
Uvezeni doprinosi i neka članstva najprije se povezuju sa zamjenskim korisnicima (placeholder). Nakon uvoza njih ponovno dodjeljujete stvarnim računima na svojoj instanci.
Direct transfer ne prenosi:
- CI/CD varijable, varijable rasporeda pipelinea i okidače pipelinea;
- deploy ključeve i deploy tokene;
- slike container registryja i package registry;
- zapisnike i artefakte CI/CD poslova;
- webhookove;
- okruženja i feature flagove;
- pravila odobravanja zahtjeva za spajanje i povezane zadatke;
- udaljene mirrore.
Pipelineovi se migriraju kao zapisi sa svojim statusima, ali bez zapisnika poslova i artefakata.
Prije početka isplanirajte kako ćete vratiti ove elemente. CI/CD varijable, deploy ključevi i deploy tokeni često sadrže lozinke i API ključeve, pa ih nakon uvoza ručno ponovno izrađujete. Slike kontejnera i paketi se ne kopiraju: ponovno ih pošaljite na svoju instancu ili ih ponovno izgradite pomoću CI-ja.
Priprema računa GitLab.com
Učinite svoju e-adresu javnom. Na GitLab.com odaberite svoj avatar u gornjem desnom kutu, a zatim Edit profile. U polju Public email odaberite svoju e-adresu i na dnu stranice odaberite Update profile settings.
Izradite osobni pristupni token. Vaša instanca koristi ovaj token za čitanje vaših podataka na GitLab.com. U lijevom izborniku profila idite na Access > Personal access tokens.
Odaberite Generate token, a zatim Legacy token.
Ispunite obrazac:
- Token name: bilo koji naziv, na primjer
migration. - Expiration date: za migraciju je dovoljno nekoliko dana.
- Select scopes: odaberite
api. Nemojte ga miješati sread_api.
Odaberite Generate token. Kopirajte token, počinje s glpat-, i spremite ga na sigurno mjesto. GitLab.com ga prikazuje samo jednom.
Ne šaljite token u chatovima ni e-poštom. Svatko tko ga ima dobiva potpuni API pristup vašem računu GitLab.com dok token ne istekne ili se ne opozove.
Uključivanje direct transfera na vašoj instanci
Prijavite se u svoju GitLab instancu kao administrator. Odaberite Admin u gornjem desnom kutu, idite na Settings > General i proširite Import and export settings. Pod Allow migrating GitLab groups and projects by direct transfer označite potvrdni okvir Enabled i odaberite Save changes.
U istom odjeljku provjerite dvije postavke koje utječu na ponovnu dodjelu korisnika nakon uvoza:
- Allow contribution mapping to administrators: kada je uključena, doprinose možete ponovno dodijeliti i administratorskim računima;
- Skip confirmation when administrators reassign placeholder users: kada je uključena, doprinosi se ponovno dodjeljuju odmah, bez odobrenja korisnika.
Povezivanje instance s GitLab.com
U gornjoj traci odaberite Create new (ikona plusa), zatim New group > Import group.
Ispunite obrazac za povezivanje:
- GitLab source instance base URL:
https://gitlab.com - Personal access token: token koji ste izradili na GitLab.com.
Odaberite Connect instance.
Otvara se stranica Import groups by direct transfer s popisom vaših grupa na GitLab.com.
Pokretanje uvoza
Pronađite grupu na popisu. U polju Path of the new group otvorite Select parent group i odaberite gdje smjestiti grupu:
- No parent izrađuje grupu najviše razine, isto kao na GitLab.com;
- postojeća grupa na vašoj instanci uvozi grupu u sebe kao podgrupu. Ako je nadređena grupa privatna, javne grupe i projekti s GitLab.com nakon uvoza postaju privatni.
Taj je odabir obavezan. Dok ne odaberete nadređenu grupu, GitLab prikazuje Select a parent group i ne pokreće uvoz.
Provjerite putanju nove grupe, prema zadanim postavkama podudara se s nazivom na GitLab.com. Ostavite odabrano Import user memberships kako bi se članovi grupe prenijeli.
Nemojte mijenjati grupu i njezine projekte na GitLab.com nakon što uvoz započne. Promjene napravljene tijekom migracije možda neće stići do vaše instance. Zamolite tim da do završetka uvoza ne šalje kod i ne uređuje zadatke.
U retku grupe odaberite Import with projects. Status se mijenja u Importing.
Ako nema gumba Import with projects, provjerite Default minimum role required to create projects u Admin > Settings > General > Visibility and access controls. Kada je postavljeno na No one, GitLab ne može uvoziti projekte.
Uvoz se izvodi u pozadini pa stranicu možete zatvoriti. Vrijeme ovisi o broju i veličini projekata: u našem testu grupa s dva mala projekta trajala je oko dvije minute.
Provjera rezultata
Kada se uvoz završi, status se mijenja u Complete.
Ako je status Failed ili Partially completed, odaberite Show errors da vidite koji elementi nisu uvezeni. Neuspjelu ili djelomičnu migraciju možete ponoviti s iste stranice ili putem API-ja.
Odaberite Migration details. Stranica Migration history prikazuje grupu i svaki projekt s njegovim statusom.
Otvorite uvezenu grupu i provjerite njezin sadržaj.
Projekti. Svi projekti grupe moraju biti na popisu.
Zadaci i zahtjevi za spajanje. U izborniku grupe otvorite Work items i Merge requests. Brojevi, oznake i prekretnice su sačuvani, a uvezeni elementi imaju značku Imported.
Repozitorij. U projektu idite na Code > Branches. Provjerite jesu li prisutne sve očekivane grane i podudaraju li se njihovi najnoviji commitovi s izvornim repozitorijem.
Autori zadataka i zahtjeva za spajanje prikazani su kao Placeholder users, na primjer Placeholder John Smith. To je očekivano, njih ćete ponovno dodijeliti kasnije u ovim uputama.
Ako zahtjev za spajanje prikazuje Cannot be merged automatically, otvorite ga i provjerite karticu Changes. Ako ne prikazuje promjene, zahtjev za spajanje nije imao commitova ni na GitLab.com, pa nema što spajati. To nije pogreška migracije.
Ponovna izrada CI/CD varijabli
Na GitLab.com otvorite projekt i idite na Settings > CI/CD, proširite Variables i zabilježite svaku varijablu s njezinim opcijama, na primjer Protected i Masked.
Na svojoj instanci otvorite isti projekt i isti odjeljak. Popis varijabli projekta je prazan.
Odaberite Add variable i izradite svaku varijablu s istim ključem, vrijednošću i opcijama. Ponovite to za varijable grupe ako ih koristite.
Rasporedi pipelinea migriraju se bez svojih varijabli. Ako vaši rasporedi koriste varijable, u projektu otvorite Build > Pipeline schedules i dodajte ih svakom rasporedu.
Ponovna dodjela zamjenskih korisnika
Tijekom uvoza GitLab izrađuje zamjenske korisnike za autore doprinosa i za uvezene članove s GitLab.com. Da biste njihove zadatke, zahtjeve za spajanje i komentare povezali sa stvarnim računima, ponovno dodijelite zamjenske korisnike. Prvo na instanci izradite račune svojeg tima kako biste imali kome dodijeliti.
Otvorite grupu najviše razine, odnosno samu uvezenu grupu ili njezinu nadređenu ako ste je uvezli kao podgrupu, idite na Manage > Members i odaberite karticu Placeholders. U ovoj grupi trebate ulogu Owner. Popis Awaiting reassignment prikazuje sve zamjenske korisnike.
U retku zamjenskog korisnika otvorite Select user i odaberite račun na svojoj instanci. Provjerite je li u pravom retku odabran pravi račun, zatim odaberite Reassign i Confirm reassignment.
Ponovna dodjela ne može se poništiti. Pogrešan odabir daje doprinose i pristup jedne osobe drugom korisniku, zato prije potvrde provjerite svaki redak.
Status se mijenja u Reassigning. Nakon minute osvježite stranicu: zamjenski korisnik prelazi na karticu Reassigned.
Zadatak sada prikazuje stvarni račun kao autora, a izvorni datum izrade je sačuvan.
Ako je Skip confirmation when administrators reassign placeholder users uključena, kao na našoj testnoj instanci, doprinosi se ponovno dodjeljuju odmah. Ako je isključena, odabrani korisnik prvo mora prihvatiti ponovnu dodjelu.
Servisni računi GitLab.com, na primjer Duo Code Review, također dolaze kao zamjenski korisnici. Nemaju pandan na vašoj instanci: ostavite ih kakvi jesu ili odaberite Do not reassign. Za mnogo korisnika koristite Reassign with CSV file na istoj kartici.
Dovršetak migracije
Opozovite token. Na GitLab.com idite na Access > Personal access tokens i odaberite Revoke pored tokena za migraciju.
Ažurirajte udaljenu adresu na računalima programera. U svakoj lokalnoj kopiji repozitorija usmjerite Git na svoju instancu:
git remote set-url origin [email protected]:group/project.git
Zamijenite group/project putanjom projekta na svojoj instanci.
Ponovno postavite integracije i automatizaciju. Webhookovi, deploy ključevi, deploy tokeni i okidači pipelinea ne migriraju se, pa ih ponovno izradite na svojoj instanci. Registrirajte CI/CD runnere na svojoj instanci. Vanjske usluge, poput obavijesti u chatu ili sustava za praćenje zadataka, ponovno povežite u postavkama svakog projekta.
Pokrenite nove pipelineove na uvezenim zahtjevima za spajanje. Uvezeni pipelineovi zadržavaju svoj izvorni status i mogu zadovoljiti uvjet Pipelines must succeed bez ponovnog izvođenja. Prije spajanja uvezenog zahtjeva za spajanje pokrenite za njega novi pipeline na svojoj instanci.
Zatvorite staru kopiju. Kada sve radi na vašoj instanci, arhivirajte ili izbrišite grupu na GitLab.com kako ondje nitko ne bi nastavio raditi.
Za odabir poslužitelja za svoju GitLab instancu pogledajte stranicu Namjenski poslužitelji za GitLab.
