将代码库从 Bitbucket Server 迁移到 GitHub Enterprise Cloud

您可以使用 GitHub CLI 将代码库从 Bitbucket Server 迁移到 GitHub Enterprise Cloud。

本文内容

关于使用 GitHub Enterprise Importer 进行代码库迁移

您可以使用 GitHub CLI 迁移单个代码库或 BitBucket Server 实例中的所有代码库。

目前不支持使用 GitHub API 从 Bitbucket Server 迁移。

先决条件

  • 我们强烈建议您先进行试运行，然后尽快完成生产迁移。要了解有关试运行的更多信息，请参阅“从 Bitbucket Server 到 GitHub Enterprise Cloud 的迁移概述”。
  • 确保您了解将要迁移的数据以及 Importer 的已知支持限制。有关更多信息，请参阅“关于从 Bitbucket Server 到 GitHub Enterprise Cloud 的迁移”。
  • 虽然不是必需的，但我们建议在生产迁移期间暂停工作。Importer 不支持增量迁移，因此迁移期间发生的任何更改都不会迁移。如果您选择不在生产迁移期间暂停工作，则需要手动迁移这些更改。
  • 对于 GitHub.com 上的目标组织，您必须是组织所有者或拥有迁移者角色。有关更多信息，请参阅“管理 Bitbucket Server 迁移的访问权限”。
  • 您需要具有管理员或超级管理员权限的 Bitbucket Server 帐户的用户名和密码。

步骤 1：安装 GitHub CLI 的 BBS2GH 扩展

如果这是您的第一次迁移，则需要安装 GitHub CLI 的 BBS2GH 扩展。有关 GitHub CLI 的更多信息，请参阅“关于 GitHub CLI”。

或者，您可以从发行页面下载 `github/gh-bbs2gh` 代码库的独立二进制文件。您可以直接运行此二进制文件，无需 `gh` 前缀。

  1. 安装 GitHub CLI。有关 GitHub CLI 的安装说明，请参阅GitHub CLI 代码库。

    注意

    您需要 2.4.0 或更高版本的 GitHub CLI。您可以使用 `gh --version` 命令检查您安装的版本。

  2. 安装 BBS2GH 扩展。

    Shell
    gh extension install github/gh-bbs2gh

任何时候，如果您需要 BBS2GH 扩展的帮助，都可以对命令使用 `--help` 标志。例如，`gh bbs2gh --help` 将列出所有可用的命令，而 `gh bbs2gh migrate-repo --help` 将列出 `migrate-repo` 命令的所有可用选项。

步骤 2：更新 GitHub CLI 的 BBS2GH 扩展

GitHub CLI 的 BBS2GH 扩展每周更新一次。为确保您使用的是最新版本，请更新扩展。

Shell
gh extension upgrade github/gh-bbs2gh

步骤 3：设置环境变量

在您可以使用 BBS2GH 扩展迁移到 GitHub Enterprise Cloud 之前，必须创建一个可以访问目标组织的个人访问令牌，然后将个人访问令牌设置为环境变量。

您还需要为您的 Bitbucket Server 用户名和密码设置环境变量，如果您的 Bitbucket Server 实例在 Windows 上运行，则还需要设置您的 SMB 密码。

  1. 创建并记录一个个人访问令牌（经典版），用于在 GitHub Enterprise Cloud 上对目标组织进行身份验证，确保令牌满足所有要求。更多信息，请参见“从 Bitbucket Server 迁移到 GitHub Enterprise Cloud 的访问管理”。

  2. 设置环境变量，将 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"

  3. 如果您迁移到具有数据驻留的 GitHub Enterprise Cloud，为了方便起见，请为您的企业设置一个**基本 API URL**环境变量。例如：

    Shell
    export TARGET_API_URL="https://api.octocorp.ghe.com"

    您将使用此变量和 --target-api-url 选项，在使用 GitHub CLI 运行的命令中。

步骤 4：设置 Blob 存储

由于许多 Bitbucket Server 实例位于防火墙之后，GitHub CLI 使用 Blob 存储作为中间位置来存储可从互联网访问的数据。

您首先需要生成要迁移数据的存档，然后将数据从防火墙后面推送到 Blob 存储。

GitHub CLI 支持以下 Blob 存储提供商：

  • Amazon Web Services (AWS) S3
  • Azure Blob 存储

在运行迁移之前，您需要使用您选择的云提供商设置一个存储容器来存储您的数据。

设置 AWS S3 存储桶

在 AWS 中，设置一个 S3 存储桶。更多信息，请参见 AWS 文档中的创建存储桶。

您还需要一个具有以下权限的 AWS 访问密钥和密钥：

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:ListBucketMultipartUploads",
                "s3:AbortMultipartUpload",
                "s3:ListBucket",
                "s3:DeleteObject",
                "s3:ListMultipartUploadParts"
            ],
            "Resource": [
                "arn:aws:s3:::github-migration-bucket",
                "arn:aws:s3:::github-migration-bucket/*"
            ]
        }
    ]
}

注意

迁移完成后，GitHub Enterprise Importer 不会从 AWS 删除您的存档。为了降低存储成本，我们建议您配置在一段时间后自动删除存档。更多信息，请参见 AWS 文档中的在存储桶上设置生命周期配置。

准备好运行迁移时，您需要向 GitHub CLI 提供您的 AWS 凭据：区域、访问密钥、密钥和会话令牌（如果需要）。您可以将它们作为参数传递，也可以设置名为 AWS_REGION、AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY 和 AWS_SESSION_TOKEN 的环境变量。

您还需要使用 --aws-bucket-name 参数传入 S3 存储桶的名称。

设置 Azure Blob 存储存储帐户

在 Azure 中，创建一个存储帐户并记下您的连接字符串。更多信息，请参见 Microsoft 文档中的管理存储帐户访问密钥。

注意

迁移完成后，GitHub Enterprise Importer 不会从 Azure Blob 存储删除您的存档。为了降低存储成本，我们建议您配置在一段时间后自动删除存档。更多信息，请参见 Microsoft 文档中的通过自动管理数据生命周期来优化成本。

准备好运行迁移时，您可以将连接字符串作为参数传递到 GitHub CLI，也可以使用名为 AZURE_STORAGE_CONNECTION_STRING 的环境变量传递。

允许网络访问

如果您已在存储帐户上配置防火墙规则，请确保您已允许访问迁移目标的 IP 范围。请参见“从 Bitbucket Server 迁移到 GitHub Enterprise Cloud 的访问管理”。

步骤 5：迁移存储库

您可以使用 gh bbs2gh migrate-repo 命令迁移存储库。

迁移存储库时，GitHub CLI 的 BBS2GH 扩展默认执行以下步骤：

  1. 连接到您的 Bitbucket Server 实例并为每个存储库生成迁移存档。
  2. 使用 SFTP（Linux）或 SMB（Windows）将迁移存档从 Bitbucket Server 实例下载到运行 GitHub CLI BBS2GH 扩展的计算机。
  3. 将迁移存档上传到您选择的 Blob 存储提供商。
  4. 使用存储在 Blob 存储提供商中的存档 URL 在 GitHub Enterprise Cloud 中启动迁移。
  5. 删除本地计算机上的迁移存档。（迁移完成后，您需要手动删除 Blob 存储提供商中的存档。）

或者，您可以使用 GitHub CLI 生成存档，手动下载该存档，然后使用 GitHub CLI 继续迁移。

允许 GitHub CLI 下载迁移存档

要迁移单个存储库，请使用 gh bbs2gh migrate-repo 命令。

您必须从可以访问以下内容的计算机执行此步骤：

  • 通过 HTTPS 访问您的 Bitbucket Server 实例
  • 如果您的 Bitbucket Server 实例运行在 Linux 上，则通过 SFTP 访问您的 Bitbucket Server 实例。一般来说，如果您可以通过 SSH 访问服务器，那么您也可以使用 SFTP。
  • 如果您的 Bitbucket Server 实例运行在 Windows 上，则通过 SMB 访问您的 Bitbucket Server 实例
  • 您选择的 Blob 存储提供商
Shell
gh bbs2gh migrate-repo --bbs-server-url BBS-SERVER-URL \
  --bbs-project PROJECT --bbs-repo CURRENT-NAME \
  --github-org DESTINATION --github-repo NEW-NAME \
  # If you are migrating to GHE.com:
  --target-api-url TARGET-API-URL
  # If your Bitbucket Server instance runs on Linux:
  --ssh-user SSH-USER --ssh-private-key PATH-TO-KEY
  # If your Bitbucket Server instance runs on Windows:
  --smb-user SMB-USER
  # If you're using AWS S3 as your blob storage provider:
  --aws-bucket-name AWS-BUCKET-NAME
  # If you are running a Bitbucket Data Center cluster or your Bitbucket Server is behind a load balancer:
  --archive-download-host ARCHIVE-DOWNLOAD-HOST

将上面命令中的占位符替换为以下值：

占位符值
BBS-SERVER-URL您的 Bitbucket Server 实例的 URL
PROJECT要迁移的存储库的 Bitbucket Server 项目密钥
CURRENT-NAME要迁移的存储库的名称
DESTINATION目标组织的名称
NEW-NAME您希望迁移后的存储库具有的名称
TARGET-API-URL企业 GHE.com 子域的基本 API URL。例如：https://api.octocorp.ghe.com。
SSH-USER如果您的 Bitbucket Server 实例运行在 Linux 上，则通过 SFTP 连接到 Bitbucket Server 时使用的用户名
PATH-TO-KEY如果您的 Bitbucket Server 实例运行在 Linux 上，则 SSH 私钥的路径，例如 ~/.ssh/id_rsa。有关 SSH 密钥要求，请参见“从 Bitbucket Server 迁移到 GitHub Enterprise Cloud 的访问管理”。
SMB-USER如果您的 Bitbucket Server 实例运行在 Windows 上，则通过 SMB 连接到 Bitbucket Server 时使用的用户名
AWS-BUCKET-NAME您的 AWS S3 存储桶的存储桶名称
ARCHIVE-DOWNLOAD-HOST用于通过 SSH 或 SMB 连接到 Bitbucket Server/Data Center 实例的主机。只有在运行Bitbucket Data Center 集群或 Bitbucket Server 位于负载均衡器之后时，才需要指定此项。

注意

如果您收到提及 Renci.SshNet 的错误，则表示 CLI 在与服务器建立 SFTP 连接以下载迁移存档时遇到问题。有关如何排查这些问题的信息，请参见“排查 GitHub Enterprise Importer 的迁移问题”。

手动下载迁移存档

默认情况下，GitHub CLI 的 BBS2GH 扩展会执行整个迁移过程，包括使用 SFTP 或 SMB 从 Bitbucket Server 实例下载迁移存档。

但是，某些客户更倾向于手动下载迁移存档，例如，因为他们的服务器不提供 SFTP 访问。在这种情况下，您可以使用 GitHub CLI 生成存档，手动下载该存档，然后使用 GitHub CLI 继续迁移。

您必须从可以访问以下内容的计算机执行此步骤：

  • 通过 HTTPS 访问您的 Bitbucket Server 实例
  • 您选择的 Blob 存储提供商

首先，仅使用以下参数运行 gh bbs2gh migrate-repo 命令：

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

将上面命令中的占位符替换为以下值：

占位符值
BBS-SERVER-URL您的 Bitbucket Server 实例的 URL
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 在 Linux 上设置为 /var/atlassian/application-data/bitbucket/shared，在 Windows 上设置为 C:\Atlassian\ApplicationData\Bitbucket\Shared，但这可能因服务器配置而异。为了帮助您识别共享主目录，请参见“排查 GitHub Enterprise Importer 的迁移问题”。

从您的 Bitbucket Server 实例下载迁移存档，并将存档存储在运行 GitHub CLI 的计算机上。

要将迁移存档导入 GitHub，请再次使用 gh bbs2gh migrate-repo 命令，并使用不同的参数集：

Shell
gh bbs2gh migrate-repo --archive-path ARCHIVE-PATH \
  --github-org DESTINATION --github-repo NEW-NAME \
  --bbs-server-url BBS-SERVER-URL \
  --bbs-project PROJECT \
  --bbs-repo CURRENT-NAME \
  # If you're using AWS S3 as your blob storage provider:
  --aws-bucket-name AWS-BUCKET-NAME
  # If you are migrating to GHE.com:
  --target-api-url TARGET-API-URL

将上面命令中的占位符替换为以下值：

占位符值
ARCHIVE-PATH从实例下载的 Bitbucket Server 迁移存档的路径
DESTINATION目标组织的名称
NEW-NAME您希望迁移后的存储库具有的名称
BBS-SERVER-URL您的 Bitbucket Server 实例的 URL
PROJECT要迁移的存储库的 Bitbucket Server 项目密钥
CURRENT-NAME要迁移的存储库的名称
AWS-BUCKET-NAME您的 AWS S3 存储桶的存储桶名称
TARGET-API-URL企业 GHE.com 子域的基本 API URL。例如：https://api.octocorp.ghe.com。

取消迁移

如果要取消迁移，请使用 abort-migration 命令，将 MIGRATION-ID 替换为 migrate-repo 返回的 ID。

Shell
gh bb2gh abort-migration --migration-id MIGRATION-ID

步骤 6：验证迁移并检查错误日志

迁移完成后，我们建议您查看迁移日志。更多信息，请参见“访问 GitHub Enterprise Importer 的迁移日志”。

我们建议您检查迁移后的存储库以确保其完整性。

步骤 7：迁移多个存储库

如果您想一次将多个存储库迁移到 GitHub Enterprise Cloud，请使用 GitHub CLI 生成迁移脚本。生成的脚本将包含迁移命令列表，每个存储库一个。

注意

生成脚本会输出一个 PowerShell 脚本。如果您使用的是终端，则需要使用 .ps1 文件扩展名输出脚本，并为Mac或Linux安装 PowerShell 以运行它。

生成迁移脚本

您必须从可以访问您的 Bitbucket Server 实例（通过 HTTPS）的计算机执行此步骤。

要生成迁移脚本，请运行 gh bbs2gh generate-script 命令。

Shell
gh bbs2gh generate-script --bbs-server-url BBS-SERVER-URL \
  --github-org DESTINATION \
  --output FILENAME \
  # If you are migrating to GHE.com:
  --target-api-url TARGET-API-URL
  # If your Bitbucket Server instance runs on Linux:
  --ssh-user SSH-USER --ssh-private-key PATH-TO-KEY
  # If your Bitbucket Server instance runs on Windows:
  --smb-user SMB-USER
  # If you are running a Bitbucket Data Center cluster or your Bitbucket Server is behind a load balancer:
  --archive-download-host ARCHIVE-DOWNLOAD-HOST

如果您希望脚本下载每个迁移存储库的迁移日志，请添加 --download-migration-logs 标志。有关迁移日志的更多信息，请参见“访问 GitHub Enterprise Importer 的迁移日志”。

将上面命令中的占位符替换为以下值：

占位符值
BBS-SERVER-URL您的 Bitbucket Server 实例的 URL
DESTINATION目标组织的名称
FILENAME生成的迁移脚本的文件名

如果您使用的是终端，请使用.ps1文件扩展名，因为生成的脚本需要PowerShell才能运行。您可以为Mac或Linux安装PowerShell。
TARGET-API-URL企业 GHE.com 子域的基本 API URL。例如：https://api.octocorp.ghe.com。
SSH-USER如果您的 Bitbucket Server 实例运行在 Linux 上，则通过 SFTP 连接到 Bitbucket Server 时使用的用户名
PATH-TO-KEY如果您的 Bitbucket Server 实例运行在 Linux 上，则 SSH 私钥的路径，例如 ~/.ssh/id_rsa。有关 SSH 密钥要求，请参见“从 Bitbucket Server 迁移到 GitHub Enterprise Cloud 的访问管理”。
SMB-USER如果您的 Bitbucket Server 实例运行在 Windows 上，则通过 SMB 连接到 Bitbucket Server 时使用的用户名
ARCHIVE-DOWNLOAD-HOST用于通过 SSH 或 SMB 连接到 Bitbucket Server/Data Center 实例的主机。只有在运行Bitbucket Data Center 集群或 Bitbucket Server 位于负载均衡器之后时，才需要指定此项。

查看迁移脚本

生成脚本后，请查看该文件，并可选择编辑脚本。

  • 如果您不想迁移任何存储库，请删除或注释掉相应的行。
  • 默认情况下，GitHub 中的存储库名称将遵循projectKey-repositoryName约定。例如，名为airports的Bitbucket Server存储库属于名为open-source（键为OS）的项目，在GitHub中将被称为OS-airports。如果您希望任何存储库在GitHub上具有不同的名称，请更新相应--github-repo标志的值。

如果您下载的是独立二进制文件而不是GitHub CLI的扩展程序，则需要更新生成的脚本以运行二进制文件而不是gh bbs2gh。

运行迁移脚本

要迁移您的存储库，请运行生成的脚本。

您必须从可以访问以下内容的计算机执行此步骤：

  • 通过 HTTPS 访问您的 Bitbucket Server 实例
  • 如果您的 Bitbucket Server 实例运行在 Linux 上，则通过 SFTP 访问您的 Bitbucket Server 实例。一般来说，如果您可以通过 SSH 访问服务器，那么您也可以使用 SFTP。
  • 如果您的 Bitbucket Server 实例运行在 Windows 上，则通过 SMB 访问您的 Bitbucket Server 实例
  • 您选择的 Blob 存储提供商

运行脚本之前，您必须设置其他环境变量才能对您的 Blob 存储提供商进行身份验证。

  • 对于AWS S3，请设置以下环境变量。
    • AWS_ACCESS_KEY_ID：您的存储桶的访问密钥 ID
    • AWS_SECRET_ACCESS_KEY：您的存储桶的密钥
    • AWS_REGION：您的存储桶所在的AWS区域
    • AWS_SESSION_TOKEN：如果您使用的是AWS临时凭据，则为会话令牌（请参阅AWS文档中的使用AWS资源的临时凭据）
  • 对于Azure Blob存储，请将AZURE_STORAGE_CONNECTION_STRING设置为Azure存储帐户的连接字符串。

仅支持使用存储帐户访问密钥的连接字符串。不支持使用共享访问签名 (SAS) 的连接字符串。有关存储帐户访问密钥的更多信息，请参阅Azure文档中的管理存储帐户访问密钥。

要迁移多个存储库，请运行您上面生成的脚本。在以下命令中，将FILENAME替换为您在生成脚本时提供的文件名。

  • 如果您使用的是终端，请使用./。

    Shell
    ./FILENAME

  • 如果您使用的是PowerShell，请使用.\。

    Shell
    .\FILENAME