Миграция с 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.