Перенос репозиториев с Bitbucket Server в GitHub Enterprise Cloud

Сведения о миграции репозитория с помощью GitHub Enterprise Importer

Вы можете перенести отдельные репозитории или все репозитории из экземпляра BitBucket Server с помощью GitHub CLI.

В настоящее время миграция с Bitbucket Server с помощью API GitHub не поддерживается.

Предварительные требования

• Чтобы убедиться, что вы понимаете известные ограничения поддержки средства импорта, ознакомьтесь с разделом Сведения о GitHub Enterprise Importer.
• Мы настоятельно рекомендуем выполнить пробную версию миграции и завершить миграцию в рабочей среде вскоре после этого. Дополнительные сведения о рекомендациях по запуску пробной версии см. в разделе Подготовка к выполнению миграции с помощью GitHub Enterprise Importer.
• Хотя это не обязательно, рекомендуется остановить работу во время миграции рабочей среды. Importer не поддерживает разностные миграции, поэтому любые изменения, происходящие во время миграции, не будут перенесены. Если вы решили не останавливать работу во время миграции рабочей среды, необходимо вручную перенести эти изменения.
• Для целевой организации в GitHub.com необходимо быть владелец организации или иметь роль миграции. Дополнительные сведения см. в разделе Granting the migrator role for GitHub Enterprise Importer.
• Вам потребуется имя пользователя и пароль для учетной записи Bitbucket Server с разрешениями администратора или суперадминистраторов.

Шаг 1. Установка BBS2GH extension of the GitHub CLI

Если это первая миграция, необходимо установить BBS2GH extension of the GitHub CLI. Дополнительные сведения о GitHub CLI см. в разделе Сведения о GitHub CLI.

1. Install the GitHub CLI. Инструкции по установке для GitHub CLI см. в репозитории GitHub CLI.

   Note: You need version 2.4.0 or newer of GitHub CLI. You can check the version you have installed with the gh --version command.

2. Установите BBS2GH extension.

   Shell

   gh extension install github/gh-bbs2gh

Каждый раз, когда вам потребуется помощь с BBS2GH extension, вы можете использовать --help флаг с командой. Например, gh bbs2gh --help отобразит список всех доступных команд и gh bbs2gh migrate-repo --help все параметры, доступные migrate-repo для команды.

Шаг 2. Обновление BBS2GH extension of the GitHub CLI

BBS2GH extension of the GitHub CLI обновляется еженедельно. Чтобы убедиться, что вы используете последнюю версию, обновите расширение.

gh extension upgrade github/gh-bbs2gh

Шаг 3. Настройка переменных среды

Прежде чем использовать BBS2GH extension для миграции в GitHub Enterprise Cloud, необходимо создать personal access token, который может получить доступ к целевой организации, а затем задать personal access token в качестве переменной среды.

Кроме того, необходимо задать переменные среды для имени пользователя и пароля Bitbucket Server, а также пароль SMB, если экземпляр Bitbucket Server работает в Windows.

1. Создайте и запишите personal access token, который будет проходить проверку подлинности для целевой организации на GitHub Enterprise Cloud, убедившись, что маркер соответствует всем требованиям. Дополнительные сведения см. в разделе Управление доступом для GitHub Enterprise Importer.

2. Задайте переменные среды, заменив TOKEN записанным ранее personal access token, USERNAME — именем пользователя учетной записи Bitbucket Server с разрешениями администратора или суперадминистраатора, а PASSWORD — паролем для учетной записи Bitbucket Server.

   • Если вы используете терминал, используйте export команду .

     Shell

     export GH_PAT="TOKEN"
     export BBS_USERNAME="USERNAME"
     export BBS_PASSWORD="PASSWORD"
     # If your Bitbucket Server instance runs on Windows
     export SMB_PASSWORD="PASSWORD"

   • Если вы используете PowerShell, используйте $env команду .

     Shell

     $env:GH_PAT="TOKEN"
     $env:BBS_USERNAME="USERNAME"
     $env:BBS_PASSWORD="PASSWORD"
     # If your Bitbucket Server instance runs on Windows
     $env:SMB_PASSWORD="PASSWORD"

Шаг 4. Настройка хранилища BLOB-объектов

Так как многие экземпляры Bitbucket Server располагаются за брандмауэрами, GitHub CLI использует хранилище BLOB-объектов в качестве промежуточного расположения для хранения данных, доступных из Интернета.

Сначала создайте архив данных, которые требуется перенести, и отправьте их в хранилище BLOB-объектов из-за брандмауэра.

GitHub CLI поддерживает следующие поставщики хранилища BLOB-объектов:

• Amazon Web Services (AWS) S3
• хранилище BLOB-объектов Azure

Перед выполнением миграции необходимо настроить контейнер хранилища с выбранным поставщиком облачных служб для хранения данных.

Настройка контейнера хранилища AWS S3

In AWS, set up a S3 bucket. For more information, see Creating a bucket in the AWS documentation.

You will also need an AWS access key and secret key with read-write access to your bucket.

Когда вы будете готовы выполнить миграцию, необходимо указать учетные данные AWS для GitHub CLI: регион, ключ доступа, секретный ключ и маркер сеанса (при необходимости). Их можно передать в качестве аргументов или задать переменные среды с именами AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEYи AWS_SESSION_TOKEN.

Также необходимо передать имя контейнера S3 с помощью аргумента --aws-bucket-name .

Настройка учетной записи хранения Хранилище BLOB-объектов Azure

В Azure создайте учетную запись хранения и запишите строку подключения. Дополнительные сведения см. в статье Управление ключами доступа к учетной записи хранения в Документация Майкрософт.

Когда вы будете готовы выполнить миграцию, вы можете передать строку подключения в GitHub CLI в качестве аргумента или передать ее с помощью переменной среды с именем AZURE_STORAGE_CONNECTION_STRING.

Шаг 5. Перенос репозитория

Вы можете перенести репозитории с помощью gh bbs2gh migrate-repo команды .

При переносе репозитория по умолчанию BBS2GH extension of the GitHub CLI выполняет следующие действия.

1. Подключается к экземпляру Bitbucket Server и создает архив миграции для каждого репозитория.
2. Загружает архив миграции из экземпляра Bitbucket Server на компьютер, на котором выполняется BBS2GH extension of the GitHub CLI, используя SFTP (Linux) или SMB (Windows)
3. Отправляет архивы миграции в выбранный поставщик хранилища BLOB-объектов.
4. Начинает миграцию в GitHub Enterprise Cloud, используя URL-адреса архивов, хранящихся у поставщика хранилища BLOB-объектов.
5. Удаляет архив миграции.

Кроме того, можно использовать GitHub CLI, чтобы создать архив, скачать его вручную, а затем использовать GitHub CLI для продолжения миграции.

• "Разрешение GitHub CLI для скачивания архива миграции"
• "Скачивание архива миграции вручную"

Разрешение GitHub CLI загружать архив миграции

Чтобы перенести один репозиторий, используйте gh bbs2gh migrate-repo команду .

Этот шаг необходимо выполнить на компьютере, который имеет доступ к:

• Экземпляр сервера Bitbucket по протоколу HTTPS
• Экземпляр Bitbucket Server через SFTP, если экземпляр Bitbucket Server работает в Linux. Как правило, если вы можете получить доступ к серверу через SSH, вы также можете использовать SFTP.
• Экземпляр Bitbucket Server через SMB, если экземпляр Bitbucket Server работает в Windows
• Выбранный поставщик хранилища BLOB-объектов

gh bbs2gh migrate-repo --bbs-server-url BBS-SERVER-URL \
  --bbs-project PROJECT --bbs-repo CURRENT-NAME \
  --github-org DESTINATION --github-repo NEW-NAME \
  # Use the following options if your Bitbucket Server instance runs on Linux
  --ssh-user SSH-USER --ssh-private-key PATH-TO-KEY
  # Use the following options if your Bitbucket Server instance runs on Windows
  --smb-user SMB-USER
  # Use the following option if you're using AWS S3 as your blob storage provider
  --aws-bucket-name AWS-BUCKET-NAME

Замените заполнители в приведенной выше команде следующими значениями.

Заполнитель | Значение | ----------- | ----- | BBS-SERVER-URL | URL-адрес экземпляра сервера Bitbucket PROJECT | Ключ для проекта Bitbucket Server репозитория, который требуется перенести. CURRENT-NAME | Имя репозитория, который требуется перенести. НАЗНАЧЕНИЕ | Имя целевой организации NEW-NAME | Имя перенесенного репозитория SSH-USER | Если экземпляр Сервера Bitbucket работает в Linux, имя пользователя, используемое при подключении к серверу Bitbucket через SFTP ПУТЬ К КЛЮЧУ | Если экземпляр Bitbucket Server работает в Linux, путь к закрытому ключу SSH, например ~/.ssh/id_rsa. Требования к ключу SSH см. в разделе Управление доступом для GitHub Enterprise Importer. SMB-USER | Если экземпляр Bitbucket Server работает в Windows, имя пользователя, используемое при подключении к серверу Bitbucket через SMB AWS-BUCKET-NAME | Имя контейнера AWS S3

Скачивание архива миграции вручную

По умолчанию BBS2GH extension of the GitHub CLI выполняет всю миграцию, включая скачивание архива миграции из экземпляра Bitbucket Server с помощью SFTP или SMB.

Однако некоторые клиенты предпочитают скачивать архив миграции вручную, так как их сервер, например, не предоставляет доступ по SFTP. В этом случае можно использовать GitHub CLI, чтобы создать архив, скачать его вручную, а затем использовать GitHub CLI для продолжения миграции.

Этот шаг необходимо выполнить с компьютера, который имеет доступ к:

• Экземпляр сервера Bitbucket по протоколу HTTPS
• Выбранный поставщик хранилища BLOB-объектов

Во-первых, используйте gh bbs2gh migrate-repo команду только со следующими аргументами:

gh bbs2gh migrate-repo --bbs-server-url BBS-SERVER-URL \
  --bbs-project PROJECT \
  --bbs-repo CURRENT-NAME

Замените заполнители в приведенной выше команде следующими значениями.

Заполнитель | Значение | ----------- | ----- | BBS-SERVER-URL | URL-адрес экземпляра сервера Bitbucket PROJECT | Ключ для проекта Bitbucket Server репозитория, который требуется перенести. CURRENT-NAME | Имя репозитория, который требуется перенести.

Будет создан архив миграции, а путь к нему будет выведен в выходных данных команды:

[12:14] [INFO] Export completed. Your migration archive should be ready on your
instance at $BITBUCKET_SHARED_HOME/data/migration/export/Bitbucket_export_9.tar

Как правило, $BITBUCKET_SHARED_HOME для параметра будет задано значение /var/atlassian/application-data/bitbucket/shared в Linux и C:\Atlassian\ApplicationData\Bitbucket\Shared Windows, но это может отличаться в зависимости от конфигурации сервера. Сведения о том, как определить общий домашний каталог, см. в разделе Устранение неполадок миграции с помощью GitHub Enterprise Importer.

Скачайте архив миграции из экземпляра Bitbucket Server и сохраните архив на компьютере, где выполняется GitHub CLI.

Чтобы импортировать архив миграции в GitHub, снова используйте gh bbs2gh migrate-repo команду с другим набором аргументов:

gh bbs2gh migrate-repo --archive-path ARCHIVE-PATH \
  --github-org DESTINATION --github-repo NEW-NAME \
  # Use the following option if you're using AWS S3 as your blob storage provider
  --aws-bucket-name AWS-BUCKET-NAME

Замените заполнители в приведенной выше команде следующими значениями.

Заполнитель | Значение | ----------- | ----- | ARCHIVE-PATH | Путь к архиву миграции Bitbucket Server, скачанного из экземпляра. НАЗНАЧЕНИЕ | Имя целевой организации NEW-NAME | Имя перенесенного репозитория AWS-BUCKET-NAME | Имя контейнера AWS S3

Шаг 6. Проверка миграции и проверка журнал ошибок

После завершения миграции рекомендуется просмотреть журнал миграции. Дополнительные сведения см. в разделе Доступ к журналам миграции для GitHub Enterprise Importer.

Мы рекомендуем проверить перенесенные репозитории для проверки правильности.

Шаг 7. Перенос нескольких репозиториев

Если вы хотите перенести несколько репозиториев в GitHub Enterprise Cloud одновременно, используйте GitHub CLI для создания скрипта миграции. Результирующий скрипт будет содержать список команд миграции, по одной для каждого репозитория.

Создание скрипта миграции

Этот шаг необходимо выполнить с компьютера, который может получить доступ к экземпляру Bitbucket Server по протоколу HTTPS.

Чтобы создать скрипт миграции, выполните gh bbs2gh generate-script команду .

gh bbs2gh generate-script --bbs-server-url BBS-SERVER-URL \
  --github-org DESTINATION \
  --output FILENAME \
  # Use the following options if your Bitbucket Server instance runs on Linux
  --ssh-user SSH-USER --ssh-private-key PATH-TO-KEY
  # Use the following options if your Bitbucket Server instance runs on Windows
  --smb-user SMB-USER

If you want the script to download the migration log for each migrated repository, add the --download-migration-logs flag. For more information about migration logs, see "Доступ к журналам миграции для GitHub Enterprise Importer."

Замените заполнители в приведенной выше команде следующими значениями.

Заполнитель | Значение | ----------- | ----- | BBS-SERVER-URL | URL-адрес экземпляра сервера Bitbucket НАЗНАЧЕНИЕ | Имя целевой организации FILENAME | Имя файла для результирующего скрипта миграции

Если вы используете терминал, используйте .ps1 расширение файла, так как для запуска созданного скрипта требуется PowerShell. Вы можете установить PowerShell для Mac или Linux. SSH-USER | Если экземпляр Сервера Bitbucket работает в Linux, имя пользователя, используемое при подключении к серверу Bitbucket через SFTP ПУТЬ К КЛЮЧУ | Если экземпляр Bitbucket Server работает в Linux, путь к закрытому ключу SSH, например ~/.ssh/id_rsa. Требования к ключу SSH см. в разделе Управление доступом для GitHub Enterprise Importer. SMB-USER | Если экземпляр Bitbucket Server работает в Windows, имя пользователя, используемое при подключении к серверу Bitbucket через SMB

Просмотр скрипта миграции

После создания скрипта просмотрите файл и при необходимости измените скрипт.

• Если есть репозитории, которые вы не хотите переносить, удалите или закомментируйте соответствующие строки.
• По умолчанию имена репозитория в GitHub будут соответствовать соглашению projectKey-repositoryName . Например, репозиторий Bitbucket Server с именем airports , который является частью open-source проекта с ключом OS, будет вызываться OS-airports в GitHub. Если вы хотите, чтобы репозитории имели другое имя в GitHub, обновите значение соответствующего --github-repo флага.

Запуск скрипта миграции

Чтобы перенести репозитории, запустите созданный скрипт.

Этот шаг необходимо выполнить на компьютере, который имеет доступ к:

• Экземпляр сервера Bitbucket по протоколу HTTPS
• Экземпляр Bitbucket Server через SFTP, если экземпляр Bitbucket Server работает в Linux. Как правило, если вы можете получить доступ к серверу через SSH, вы также можете использовать SFTP.
• Экземпляр Bitbucket Server через SMB, если экземпляр Bitbucket Server работает в Windows
• Выбранный поставщик хранилища BLOB-объектов

Перед запуском скрипта необходимо задать дополнительные переменные среды для проверки подлинности в поставщике хранилища BLOB-объектов.

• Для AWS S3 задайте следующие переменные среды.
  • AWS_ACCESS_KEY: ключ доступа для контейнера.
  • AWS_SECRET_KEY: секретный ключ для контейнера.
  • AWS_REGION: регион AWS, в котором находится ваш контейнер.
  • AWS_SESSION_TOKEN: маркер сеанса, если вы используете временные учетные данные AWS (см. раздел Использование временных учетных данных с ресурсами AWS в документации по AWS).
• Для Хранилище BLOB-объектов Azure задайте AZURE_STORAGE_CONNECTION_STRING строку подключения для учетной записи хранения Azure.

Поддерживаются только строки подключения, использующие ключи доступа к учетной записи хранения. Строки подключения, использующие подписанные URL-адреса (SAS), не поддерживаются. Дополнительные сведения о ключах доступа к учетной записи хранения см. в статье Управление ключами доступа к учетной записи хранения в документации по Azure.

To migrate multiple repositories, run the script you generated above. Replace FILENAME in the commands below with the filename you provided when generating the script.

• If you're using Terminal, use ./.
  Shell

  ./FILENAME

• If you're using PowerShell, use .\.
  Shell

  .\FILENAME