Міграція з GitLab.com на власний GitLab

Коли команда переходить з GitLab.com на свою інсталяцію, код становить лише частину роботи. Задачі, merge requests, мітки, віхи та їхня історія теж мають переїхати, і бажано без ручного копіювання.

Для цього в GitLab є вбудований спосіб, direct transfer. Ваша інсталяція підключається до GitLab.com через HTTPS за допомогою персонального токена доступу й копіює групу разом з її проєктами. Імпорт виконується у фоні, а після завершення кожен перенесений об'єкт можна перевірити.

У цьому посібнику показано повне перенесення однієї групи: підготовка GitLab.com, запуск імпорту, перевірка результату та кроки, які direct transfer не виконує. Усі кроки перевірено на реальній міграції з GitLab.com на GitLab 19.5 під Ubuntu 26.04.

Що потрібно перед міграцією

Встановлена й робоча власна інсталяція GitLab. Якщо її ще немає, спочатку встановіть GitLab, див. посібник Як встановити GitLab на виділений сервер.

Доступ адміністратора до вашої інсталяції GitLab.

Роль Owner у групі, яку ви переносите з GitLab.com. На сторінці імпорту показано лише групи, де у вас роль Owner.

Вихідний доступ через HTTPS з вашого сервера до https://gitlab.com.

Достатньо вільного місця на диску для всіх репозиторіїв, що переносяться, а також вільне місце в /tmp: там GitLab розпаковує тимчасові архіви міграції.

У всьому посібнику замініть gitlab.example.com на домен своєї інсталяції.

Що переноситься

Direct transfer переносить:

• групу та її проєкти;
• репозиторії з усіма гілками та історією комітів, хеші комітів не змінюються;
• задачі та merge requests з початковими номерами;
• мітки, віхи та історію дій;
• початкові дати створення.

Перенесені дії користувачів і частина членства в групах спочатку прив'язуються до користувачів-заглушок (placeholder users). Після імпорту ви перепризначаєте їх на реальні облікові записи своєї інсталяції.

Direct transfer не переносить:

• змінні CI/CD, змінні розкладів пайплайнів і тригери пайплайнів;
• deploy keys і deploy tokens;
• образи container registry і package registry;
• логи джобів CI/CD і артефакти джобів;
• вебхуки;
• оточення (environments) і feature flags;
• правила схвалення merge requests і пов'язані задачі (linked issues);
• remote mirrors.

Пайплайни переносяться як записи зі своїми статусами, але без логів джобів і артефактів.

Підготовка облікового запису на GitLab.com

Зробіть адресу електронної пошти публічною. На GitLab.com натисніть на аватар у правому верхньому куті, потім Edit profile. У полі Public email виберіть свою адресу й натисніть Update profile settings унизу сторінки.

Створіть персональний токен доступу. За його допомогою ваша інсталяція читає дані на GitLab.com. У лівому меню профілю перейдіть до Access > Personal access tokens.

Натисніть Generate token і виберіть Legacy token.

Заповніть форму:

• Token name: будь-яке ім'я, наприклад migration.
• Expiration date: для міграції достатньо кількох днів.
• Select scopes: позначте api. Не сплутайте з read_api.

Натисніть Generate token. Скопіюйте токен, він починається з glpat-, і збережіть його в надійному місці. GitLab.com показує його лише один раз.

Увімкнення direct transfer на вашій інсталяції

Увійдіть у свою інсталяцію GitLab як адміністратор. Натисніть Admin у правому верхньому куті, перейдіть до Settings > General і розгорніть розділ Import and export settings. У пункті Allow migrating GitLab groups and projects by direct transfer позначте прапорець Enabled і натисніть Save changes.

У цьому ж розділі перевірте два налаштування, які впливають на перепризначення користувачів після імпорту:

• Allow contribution mapping to administrators: якщо увімкнено, дії можна перепризначати й на облікові записи адміністраторів;
• Skip confirmation when administrators reassign placeholder users: якщо увімкнено, дії перепризначаються одразу, без підтвердження з боку користувача.

Підключення інсталяції до GitLab.com

Натисніть Create new (значок плюса) на верхній панелі, потім New group > Import group.

Заповніть форму підключення:

• GitLab source instance base URL: https://gitlab.com
• Personal access token: токен, створений на GitLab.com.

Натисніть Connect instance.

Відкриється сторінка Import groups by direct transfer зі списком ваших груп на GitLab.com.

Запуск імпорту

Знайдіть групу в списку. У колонці Path of the new group відкрийте Select parent group і виберіть, куди помістити групу:

• No parent створює групу верхнього рівня, як на GitLab.com;
• наявна група вашої інсталяції: групу буде імпортовано в неї як підгрупу. Якщо батьківська група приватна, публічні групи та проєкти з GitLab.com після імпорту стануть приватними.

Перевірте шлях нової групи, за замовчуванням він збігається з ім'ям на GitLab.com. Залиште прапорець Import user memberships, щоб перенести учасників групи.

Натисніть Import with projects у рядку групи. Статус зміниться на Importing.

Імпорт виконується у фоні, сторінку можна закрити. Час залежить від кількості та розміру проєктів: у нашому тесті група з двома невеликими проєктами перенеслася приблизно за дві хвилини.

Перевірка результату

Коли імпорт завершиться, статус зміниться на Complete.

Якщо статус Failed або Partially completed, натисніть Show errors, щоб побачити, які об'єкти не перенеслися. Невдалу або часткову міграцію можна повторити на тій самій сторінці або через API.

Натисніть Migration details. На сторінці Migration history показано групу та кожен проєкт з його статусом.

Відкрийте імпортовану групу й перевірте її вміст.

Проєкти. Усі проєкти групи мають бути в списку.

Задачі та merge requests. Відкрийте Work items і Merge requests у меню групи. Номери, мітки та віхи зберігаються, а в імпортованих об'єктів є позначка Imported.

Репозиторій. У проєкті перейдіть до Code > Branches. Перевірте, що всі потрібні гілки на місці та їхні останні коміти збігаються з вихідним репозиторієм.

Якщо в merge request стоїть Cannot be merged automatically, відкрийте його й перегляньте вкладку Changes. Якщо змін немає, отже, у merge request не було комітів і на GitLab.com, і зливати нічого. Це не помилка міграції.

Перенесення змінних CI/CD

На GitLab.com відкрийте проєкт, перейдіть до Settings > CI/CD, розгорніть розділ Variables і випишіть кожну змінну з її параметрами, наприклад Protected і Masked.

На своїй інсталяції відкрийте той самий проєкт і той самий розділ. Список змінних проєкту порожній.

Натисніть Add variable і створіть кожну змінну з тим самим ключем, значенням і параметрами. Якщо ви використовуєте змінні групи, повторіть те саме для них.

Розклади пайплайнів переносяться без своїх змінних. Якщо розклади використовують змінні, відкрийте в проєкті Build > Pipeline schedules і додайте їх до кожного розкладу.

Перепризначення користувачів-заглушок

Під час імпорту GitLab створює користувачів-заглушок для авторів дій і для імпортованих учасників з GitLab.com. Щоб їхні задачі, merge requests і коментарі належали реальним обліковим записам, перепризначте заглушки. Спочатку створіть на інсталяції облікові записи своєї команди, щоб було на кого перепризначати.

Відкрийте групу верхнього рівня: саму імпортовану групу або її батьківську, якщо ви імпортували її як підгрупу. Перейдіть до Manage > Members і відкрийте вкладку Placeholders. Для цього потрібна роль Owner у цій групі. У списку Awaiting reassignment показано всіх користувачів-заглушок.

У рядку заглушки відкрийте Select user і виберіть обліковий запис на своїй інсталяції. Переконайтеся, що в потрібному рядку вибрано потрібний обліковий запис, потім натисніть Reassign і Confirm reassignment.

Статус зміниться на Reassigning. За хвилину оновіть сторінку: заглушка перейде до вкладки Reassigned.

Тепер автором задачі вказано реальний обліковий запис, а початкова дата створення збереглася.

Службові облікові записи GitLab.com, наприклад Duo Code Review, теж надходять як заглушки. На вашій інсталяції їм немає відповідності: залиште їх як є або виберіть Do not reassign. Якщо користувачів багато, скористайтеся Reassign with CSV file на тій самій вкладці.

Завершення міграції

Відкличте токен. На GitLab.com перейдіть до Access > Personal access tokens і натисніть Revoke поруч із токеном для міграції.

Оновіть адресу репозиторію на комп'ютерах розробників. У кожній локальній копії репозиторію вкажіть Git нову адресу:

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

Замініть group/project на шлях проєкту на вашій інсталяції.

Заново налаштуйте інтеграції та автоматизацію. Вебхуки, deploy keys, deploy tokens і тригери пайплайнів не переносяться, тому створіть їх на своїй інсталяції. Зареєструйте ранери CI/CD на своїй інсталяції. Заново підключіть зовнішні сервіси, наприклад сповіщення в чат або трекери задач, у налаштуваннях кожного проєкту.

Запустіть нові пайплайни в імпортованих merge requests. Імпортовані пайплайни зберігають початковий статус і можуть задовольнити умову Pipelines must succeed без повторного запуску. Перед злиттям імпортованого merge request запустіть для нього новий пайплайн на своїй інсталяції.

Закрийте стару копію. Коли на вашій інсталяції все працює, заархівуйте або видаліть групу на GitLab.com, щоб у ній більше ніхто не працював.

Щоб підібрати сервер для своєї інсталяції GitLab, див. сторінку Виділені сервери для GitLab.