将存储库从 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 的概述”。
  • 确保了解将要迁移的数据以及导入程序已知的支持限制。有关详细信息，请参阅“关于从 Bitbucket Server 迁移到 GitHub Enterprise Cloud”。
  • 虽然并非必需，但建议在生产迁移期间停止工作。 Importer 不支持增量迁移，因此迁移期间发生的任何更改都不会迁移。 如果选择在生产迁移期间不停止工作，需要手动迁移这些更改。
  • 对于 GitHub.com 上的目标组织，你必须是组织所有者或拥有迁移者角色。 有关详细信息，请参阅“管理从 Bitbucket Server 迁移的访问权限”。
  • 你需要具有管理员或超级管理员权限的 Bitbucket Server 帐户的用户名和密码。

步骤 1：安装 BBS2GH extension of the GitHub CLI

如果这是第一次迁移，需要安装 BBS2GH extension of the GitHub CLI。 有关 GitHub CLI 的详细信息，请参阅“关于 GitHub CLI”。

此外，也可以从 github/gh-bbs2gh 存储库的版本页面下载一个独立的二进制文件。 可以直接运行此二进制文件，无需使用前缀 gh。

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

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

  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 每周更新一次。 为了确保使用的是最新版本，请更新扩展。

Shell
gh extension upgrade github/gh-bbs2gh

步骤 3：设置环境变量

在使用 BBS2GH extension 迁移到 GitHub Enterprise Cloud 之前，必须创建可以访问目标组织的 personal access token，然后将 personal access token 设置为环境变量。

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

  1. 创建并记录一个 personal access token (classic)，用于在 GitHub Enterprise Cloud 上为目标组织进行身份验证，确保令牌满足所有要求。 有关详细信息，请参阅“管理从 Bitbucket Server 迁移的访问权限”。

  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"

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

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

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

步骤 4：设置 blob 存储

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

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

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

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

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

设置 AWS S3 存储桶

在 AWS 中，设置 S3 Bucket。 有关详细信息，请参阅 AWS 文档中的创建 Bucket。

还需要具有以下权限的 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 文档中的 Bucket 生命周期配置。

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

你还需要使用 --aws-bucket-name 参数传入 S3 Bucket 的名称。

设置 Azure Blob 存储存储帐户

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

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

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

允许网络访问

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

步骤 5：迁移存储库

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

迁移存储库时，BBS2GH extension of the GitHub CLI 默认将执行以下步骤：

  1. 连接到 Bitbucket Server 实例并为每个存储库生成迁移存档
  2. 使用 SFTP (Linux) 或 SMB (Windows)，将迁移存档从 Bitbucket Server 实例下载到运行 BBS2GH extension of the GitHub CLI 的计算机
  3. 将迁移存档上传到所选的 blob 存储提供程序
  4. 通过使用 blob 存储提供程序存储的存档 URL 在 GitHub Enterprise Cloud 中开始迁移
  5. 从本地计算机中删除迁移存档。 （迁移完成后，需要手动从 Blob 存储提供程序中删除存档。）

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

允许 GitHub CLI 下载迁移存档

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

必须在可以访问以下内容的计算机上执行此步骤:

  • 通过 HTTPS 访问 Bitbucket Server 实例
  • 通过 SFTP 访问 Bitbucket Server 实例（如果 Bitbucket Server 实例在 Linux 上运行）。 通常，如果可以通过 SSH 访问该服务器，则也可以使用 SFTP。
  • 通过 SMB 访问 Bitbucket Server 实例（如果 Bitbucket Server 实例在 Windows 上运行）
  • 所选的 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-URLBitbucket 服务器实例的 URL
PROJECT要迁移的存储库的 Bitbucket Server 项目的密钥
CURRENT-NAME要迁移的存储库的名称
目标目标组织的名称
NEW-NAME希望已迁移的存储库具有的名称
TARGET-API-URL企业子域 GHE.com 的基本 API URL。 例如：https://api.octocorp.ghe.com。
SSH-USER如果 Bitbucket 服务器实例在 Linux 上运行，则为通过 SSH 连接到 Bitbucket 服务器时使用的用户名
PATH-TO-KEY如果 Bitbucket 服务器实例在 Linux 上运行，则为 SSH 私钥的路径，例如 ~/.ssh/id_rsa。 有关 SSH 密钥的要求，请参阅“管理从 Bitbucket Server 迁移的访问权限”。
SMB-USER如果 Bitbucket Server 实例在 Windows 上运行，则为通过 SMB 连接到 Bitbucket Server 时使用的用户名
AWS-BUCKET-NAMEAWS S3 桶的桶名称
ARCHIVE-DOWNLOAD-HOST用于通过 SSH 或 SMB 连接到 Bitbucket Server/数据中心实例的主机。 仅当运行 Bitbucket 数据中心群集或 Bitbucket Server 位于负载均衡器后面时，才需指定此项。

注意：如果收到提及 Renci.SshNet 的错误，则 CLI 在与服务器建立 SFTP 连接以下载迁移存档文件时会遇到问题。 有关如何解决这些问题的信息，请参阅“使用 GitHub Enterprise Importer 排查迁移问题”。

手动下载迁移存档

默认情况下，BBS2GH extension of the GitHub CLI 执行整个迁移，包括使用 SFTP 或 SMB 从 Bitbucket 服务器实例下载迁移存档。

但是，某些客户更喜欢手动下载迁移存档，比如，因为其服务器不提供 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-URLBitbucket 服务器实例的 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 服务器实例下载迁移存档，并将存档存储在运行 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 迁移存档的路径
目标目标组织的名称
NEW-NAME希望已迁移的存储库具有的名称
BBS-SERVER-URLBitbucket 服务器实例的 URL
PROJECT要迁移的存储库的 Bitbucket Server 项目的密钥
CURRENT-NAME要迁移的存储库的名称
AWS-BUCKET-NAMEAWS 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 才能运行它。

生成迁移脚本

必须在可通过 HTTPS 访问 Bitbucket Server 实例的计算机上执行此步骤。

若要生成迁移脚本，请运行 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-URLBitbucket 服务器实例的 URL
目标目标组织的名称
FILENAME生成的迁移脚本的文件名

如果使用终端，请使用 .ps1 文件扩展名，因为生成的脚本需要 PowerShell 才能运行。 可以安装适用于 Mac 或 Linux 的 PowerShell。
TARGET-API-URL企业子域 GHE.com 的基本 API URL。 例如：https://api.octocorp.ghe.com。
SSH-USER如果 Bitbucket 服务器实例在 Linux 上运行，则为通过 SSH 连接到 Bitbucket 服务器时使用的用户名
PATH-TO-KEY如果 Bitbucket 服务器实例在 Linux 上运行，则为 SSH 私钥的路径，例如 ~/.ssh/id_rsa。 有关 SSH 密钥的要求，请参阅“管理从 Bitbucket Server 迁移的访问权限”。
SMB-USER如果 Bitbucket Server 实例在 Windows 上运行，则为通过 SMB 连接到 Bitbucket Server 时使用的用户名
ARCHIVE-DOWNLOAD-HOST用于通过 SSH 或 SMB 连接到 Bitbucket Server/数据中心实例的主机。 仅当运行 Bitbucket 数据中心群集或 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 实例
  • 通过 SFTP 访问 Bitbucket Server 实例（如果 Bitbucket Server 实例在 Linux 上运行）。 通常，如果可以通过 SSH 访问该服务器，则也可以使用 SFTP。
  • 通过 SMB 访问 Bitbucket Server 实例（如果 Bitbucket Server 实例在 Windows 上运行）
  • 所选的 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