将仓库从 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 存储库。

    注意：您需要 GitHub CLI 2.4.0 或更高版本。您可以使用 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 迁移的访问权限”。

  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"

步骤 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 文档中的在存储桶上设置生命周期配置。

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

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

设置 Azure Blob 存储存储帐户

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

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

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

步骤 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 \
  # 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
  # Use the following option 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您希望迁移后的仓库名称
SSH-USER如果您的 Bitbucket Server 实例运行在 Linux 上，则通过 SFTP 连接到 Bitbucket Server 时使用的用户名
PATH-TO-KEY如果您的 Bitbucket Server 实例运行在 Linux 上，则 SSH 私钥的路径，例如 ~/.ssh/id_rsa。有关 SSH 密钥要求，请参阅 "管理从 Bitbucket Server 迁移的访问权限"。
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 \
  # 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 迁移存档的路径。
DESTINATION目标组织的名称
NEW-NAME您希望迁移后的仓库名称
BBS-SERVER-URL您 Bitbucket Server 实例的 URL
PROJECT要迁移的存储库所在的 Bitbucket Server 项目的键
CURRENT-NAME您要迁移的仓库名称
AWS-BUCKET-NAME您的 AWS S3 存储桶的存储桶名称

取消迁移

如果要取消迁移，请使用 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 \
  # 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 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。
SSH-USER如果您的 Bitbucket Server 实例运行在 Linux 上，则通过 SFTP 连接到 Bitbucket Server 时使用的用户名
PATH-TO-KEY如果您的 Bitbucket Server 实例运行在 Linux 上，则 SSH 私钥的路径，例如 ~/.ssh/id_rsa。有关 SSH 密钥要求，请参阅 "管理从 Bitbucket Server 迁移的访问权限"。
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 标志的值。

如果您将 BBS2GH 作为独立二进制文件下载而不是作为 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：您存储桶的访问密钥
    • AWS_SECRET_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