Использование GitVerse Migration Tool

GitVerse Migration Tool — инструмент для массовой миграции репозиториев из GitLab в GitVerse. Инструмент получает список репозиториев для миграции и запускает задачу переноса через публичное API GitVerse.

Руководство подходит для двух сценариев: миграция для личного аккаунта и миграция для организации.

На этой странице

1. Скачивание и запуск Migration Tool;
2. Настройка подключения к публичному API GitVerse;
3. Настройка подключения к API GitLab;
4. Проверка доступа;
5. Определение пространства импорта;
6. Создание списка репозиториев и миграция по файлу;
7. Типовые проблемы и их решения;
8. Чек-лист миграции;
9. Миграция с других платформ через веб-интерфейс.

1. Скачивание и запуск Migration Tool

Скачайте архив нужной платформы со страницы Releases репозитория GitVerse Migration Tool. Распакуйте архив и запустите бинарный файл gmt из каталога, где он находится:

./gmt --help

Если файл не имеет права на запуск:

chmod +x ./gmt

Консольный режим

По умолчанию запускается консольный режим. Работа состоит из двух этапов:

Генерация файла списка репозиториев — флаг --config-out.
Выполнение миграции по файлу — флаг --config.

Примеры команд приведены в разделе 6.

Интерактивный режим

Интерактивная форма включается явно флагом -i:

./gmt -i

По умолчанию используются адреса API https://api.gitverse.ru и https://gitlab.com/api/v4; при необходимости их можно заменить нужными. Токены вводятся в форме замаскированными; в консольном режиме их передают параметрами командной строки.

Основные параметры командной строки

Параметр	Короткий флаг	Описание
`--gitverse-url`	`-u`	Полный адрес Public API GitVerse
`--source-url`	`-s`	Адрес API GitLab
`--gitverse-token`	`-k`	Токен GitVerse
`--source-token`	`-t`	Токен GitLab
`--gitverse-owner`	`-o`	Пространство GitVerse для импорта
`--source-group`	—	Группа GitLab для отбора репозиториев
`--include-subgroups`	—	Включить вложенные группы
`--all-projects`	—	Загрузить все проекты, доступные токену; по умолчанию загружаются проекты, доступные пользователю по членству
`--config-out`	—	Создать файл со списком репозиториев
`--config`	`-c`	Выполнить миграцию по существующему файлу
`--interactive`	`-i`	Открыть интерактивный режим
`--lang`	`-l`	Язык интерфейса: `ru` или `en`
`--help`	`-h`	Показать справку

Токены в файл конфигурации не записываются.

2. Настройка подключения к публичному API GitVerse

Информация из официальной документации GitVerse: разделы Разработчикам → Публичный API и Совместная работа → Аутентификация → Токены.

2.1. Адрес API и обязательные заголовки

Для работы с публичным API GitVerse используется базовый адрес:

https://api.gitverse.ru

Для другого GitVerse-инстанса укажите полный внешний адрес его публичного API.

Каждый запрос обязан содержать два заголовка:

Заголовок	Значение	Назначение
`Authorization`	`Bearer YOUR_TOKEN`	Аутентификация (обязательный)
`Accept`	`application/vnd.gitverse.object+json;version=latest`	Формат ответа GitVerse API (обязательный)

Пример первого запроса:

curl -s -H "Authorization: Bearer <GITVERSE_TOKEN>" \
  -H "Accept: application/vnd.gitverse.object+json;version=latest" \
  https://api.gitverse.ru/user

Info

Токен предоставляет доступ к вашему аккаунту GitVerse через API. Храните его в безопасном месте и не передавайте случайным образом.

2.2. Генерация токена GitVerse

Информация из документации GitVerse (Аутентификация → Токены).

Шаг 1. Войдите в GitVerse и нажмите на иконку пользователя в правом верхнем углу.

Шаг 2. В открывшейся панели выберите Настройки.

Шаг 3. Перейдите на вкладку Управление токенами.

Шаг 4. Введите имя токена.

Шаг 5. Для Migration Tool выберите минимальный набор разрешений:

user — Read;
organization — Read;
repository — Read and Write.

Для остальных категорий оставьте No Access. repository: Read and Write требуется для запуска миграции и удаления репозитория при неудаче; organization: Read — для списка пространств; user: Read — для проверки GET /user.

Шаг 6. Нажмите Генерировать токен.

Шаг 7. Скопируйте и сохраните токен.

После создания токен обычно отображается один раз. Скопируйте его сразу и храните безопасно.

Примечание

Info

Для миграции в организацию убедитесь, что вы являетесь членом целевой организации и обладаете правом создавать репозитории в ней.

3. Настройка подключения к API GitLab

Аналогично GitVerse, для доступа к GitLab используется его API и токен.

3.1. Адрес API GitLab

https://gitlab.com/api/v4

Для аутентификации в запросах используется заголовок:

Заголовок	Значение
`PRIVATE-TOKEN`	`YOUR_GITLAB_TOKEN`

Пример запроса:

curl -s --header "PRIVATE-TOKEN: <GITLAB_TOKEN>" \
  https://gitlab.com/api/v4/user

3.2. Генерация токена GitLab

Шаг 1. Войдите в GitLab.

Шаг 2. Откройте Settings → Access Tokens.

Шаг 3. Создайте Personal Access Token.

Шаг 4. Выдайте минимальные scope:

read_api — чтение API, включая список проектов;
read_repository — чтение содержимого приватных репозиториев по Git-over-HTTP.

Для Migration Tool используйте эти два scope.

Шаг 5. Создайте токен и скопируйте его — он больше не будет показан.

Info

Токен GitLab передается Migration Tool параметром командной строки (-t). При запуске миграции инструмент передает его GitVerse Public API для доступа сервиса к исходным репозиториям; в URL токен не включается.

4. Проверка доступа

Перед запуском миграции проверьте, что оба токена действуют.

Рекомендуемый способ проверки

Запустите Migration Tool в интерактивном режиме и нажмите Enter на форме подключения. Инструмент проверит адреса и токены обоих API через GET /user и покажет результат на экране.

Ручные запросы curl ниже можно использовать как альтернативный способ диагностики.

Шаг 1. Проверьте токен GitVerse:

curl -s -H "Authorization: Bearer <GITVERSE_TOKEN>" \
  -H "Accept: application/vnd.gitverse.object+json;version=latest" \
  https://api.gitverse.ru/user

Ожидаемый результат (200 OK) — ваш профиль.

{
  "id": 64964,
  "login": "test",
  "html_url": "https://gitverse.ru/test",
  "public_repos": 58
}

Шаг 2. Проверьте токен GitLab:

curl -s --header "PRIVATE-TOKEN: <GITLAB_TOKEN>" \
  https://gitlab.com/api/v4/user | python3 -m json.tool

Info

Токен GitVerse привязан к конкретному инстансу. Всегда проверяйте токен на том адресе API, куда выполняется миграция.

4.1. Проверка прямой сетевой видимости

Проверка API из Migration Tool подтверждает только доступность токенов. Для массовой миграции дополнительно убедитесь, что GitVerse имеет сетевую видимость с GitLab-инстансом и может устанавливать к нему соединения. Проверку выполняйте на хосте или внутри контейнера GitVerse:

curl -I https://gitlab.com

Для локального GitLab вместо gitlab.com укажите его сетевое имя или адрес, доступные из GitVerse. Если этот запрос не выполняется из среды GitVerse, Migration Tool не сможет исправить проблему: нужно настроить DNS, маршрутизацию, firewall или прокси между сервисами.

5. Определение пространства импорта

Репозитории переносятся в пространство GitVerse (пространство импорта):

Пространство	Когда использовать
Личная область пользователя	Владелец токена — пользователь
Организация	Репозитории принадлежат команде

Info

Если пространство в файле конфигурации не указано, используется текущее пространство пользователя GitVerse. Для миграции в организацию укажите ее имя в поле gitverse_owner верхнего уровня файла конфигурации.

6. Создание списка репозиториев и миграция по файлу

6.1. Генерация списка репозиториев

Команда получает доступные репозитории GitLab и сохраняет выбранный список в файл конфигурации (например, migration.json). Токены в файл не записываются.

./gmt \
  --config-out migration.json \
  -k "$GITVERSE_TOKEN" \
  -t "$GITLAB_TOKEN" \
  --source-group=team/backend \
  --include-subgroups

Без --include-subgroups в список попадут только репозитории непосредственно указанной группы.

Без --source-group выбираются проекты, доступные пользователю по членству. Флаг --all-projects расширяет выбор до всех проектов, доступных токену.

6.2. Редактирование файла

После генерации migration.json его можно открыть и отредактировать вручную: например, изменить имена и описания репозиториев, пространство импорта или удалить отдельные записи.

6.3. Выполнение миграции по файлу

Отредактированный файл передается на выполнение через --config:

./gmt \
  -c migration.json \
  -k "$GITVERSE_TOKEN" \
  -t "$GITLAB_TOKEN"

Мигрируют только репозитории, перечисленные в файле. После каждой попытки в тот же файл записываются status и errors; исходные адреса, пространство и настройки репозиториев сохраняются. Если пространство не указано, используется текущее пространство пользователя GitVerse.

Info

Профиль миграции создается только при явном указании --config-out, а файл, переданный через --config, используется для выполнения миграции и записи ее результатов.

7. Типовые проблемы и их решения

Проблема	Причина	Решение
`401 Unauthorized` на публичном API	Токен недействителен или выдан для другого инстанса	Проверьте токен через `GET /user` на целевой API
`decode configured repository 1: path and source URL are required`	Не указан `clone_url`	Добавьте `clone_url` в запись репозитория
`validate migration parameters: API token is required`	Токены не переданы	Передайте `-k` (GitVerse) и `-t` (GitLab)
`409 Conflict` при миграции	Репозиторий уже существует	Удалите или переименуйте существующий репозиторий
Репозиторий пуст или отсутствует после миграции	Проверьте итоговый статус и текст ошибки в поле `errors`	Исправьте причину и повторите миграцию по обновленному профилю

8. Чек-лист миграции

До миграции

токены GitVerse и GitLab созданы с нужными правами доступа;
токены проверены на целевом API (GET /user) или в интерактивном режиме;
из среды GitVerse доступен GitLab-инстанс (DNS и HTTPS);
определено пространство импорта: пользователь или организация;
для организации: пользователь состоит в организации и может создавать репозитории;
инструмент gitverse-migrate скачан и имеет права на запуск.

Info

Опционально может быть выполнена пробная миграция одного репозитория, затем созданный репозиторий удален вручную.

Миграция

список репозиториев сгенерирован: --config-out migration.json --source-group ...;
файл отредактирован: имена, описания, пространство импорта, лишние записи удалены;
миграция запущена по файлу: -c migration.json;
токены переданы через -k и -t (в файл не записываются);
статус доведен до finished, errors отсутствуют.

После миграции

количество веток и тегов совпадает с исходным репозиторием;
пользователь самостоятельно настроил репозитории для команды: видимость, соавторы, защита веток.

9. Миграция с других платформ через веб-интерфейс

Если у вас уже есть репозиторий на другой платформе, его можно перенести на GitVerse прямо из веб-интерфейса — без установки CLI-инструмента. При импорте копируются файлы, история изменений, все ветки и коммиты, т. е. вся структура git-репозитория. Порядок действий описан на странице Импорт репозитория

Проводник

Использование GitVerse Migration Tool

На этой странице

1. Скачивание и запуск Migration Tool

Консольный режим

Интерактивный режим

Основные параметры командной строки

2. Настройка подключения к публичному API GitVerse

2.1. Адрес API и обязательные заголовки

2.2. Генерация токена GitVerse

3. Настройка подключения к API GitLab

3.1. Адрес API GitLab

3.2. Генерация токена GitLab

4. Проверка доступа

4.1. Проверка прямой сетевой видимости

5. Определение пространства импорта

6. Создание списка репозиториев и миграция по файлу

6.1. Генерация списка репозиториев

6.2. Редактирование файла

6.3. Выполнение миграции по файлу

7. Типовые проблемы и их решения

8. Чек-лист миграции

До миграции

Миграция

После миграции

9. Миграция с других платформ через веб-интерфейс

Вид графа

На этой странице

Связанные страницы