Skip to main content
我们经常发布文档更新，此页面的翻译可能仍在进行中。 有关最新信息，请访问英语文档。
All products
迁移

将存储库从 Bitbucket Server 迁移到 GitHub Enterprise Cloud

本文内容

可以使用 GitHub CLI 将存储库从 Bitbucket Server 迁移到 GitHub Enterprise Cloud。

注意：使用 GitHub Enterprise Importer 从 Bitbucket Server 迁移目前处于专用 beta 版中，可能会发生更改。 若要请求访问 beta 版，请参阅加入 Bitbucket Server 迁移等待列表。

关于使用 GitHub Enterprise Importer 进行存储库迁移

可以使用 GitHub CLI 从 BitBucket Server 实例迁移单个存储库或所有存储库。

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

先决条件

  • To ensure you understand the known support limitations of the Importer, review "关于 GitHub Enterprise Importer."
  • 强烈建议执行迁移的试运行，然后在不久之后完成生产迁移。 若要详细了解试运行最佳做法，请参阅“准备使用 GitHub Enterprise Importer 运行迁移”。
  • 虽然并非必需，但建议在生产迁移期间停止工作。 Importer 不支持增量迁移，因此迁移期间发生的任何更改都不会迁移。 如果选择在生产迁移期间不停止工作，需要手动迁移这些更改。
  • 对于 GitHub.com 上的目标组织，你必须是组织所有者或拥有迁移者角色。 有关详细信息，请参阅“为 GitHub Enterprise Importer 授予迁移者角色”。
  • 你需要具有管理员或超级管理员权限的 Bitbucket Server 帐户的用户名和密码。

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

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

  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 上为目标组织进行身份验证，确保令牌满足所有要求。 有关详细信息，请参阅“管理 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 存储作为中间位置来存储可从 Internet 访问的数据。

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

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

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

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

设置 AWS S3 存储桶

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

还需要一个 AWS 访问密钥和对 Bucket 具有 read-write 权限的密钥。

注意：迁移完成后，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 中的通过自动管理数据生命周期来优化成本。

When you're ready to run your migration, you can either pass your connection string into the GitHub CLI as an argument, or pass it in using an environment variable called AZURE_STORAGE_CONNECTION_STRING.

步骤 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. 删除迁移存档

或者，可以使用 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 \
  # 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 | Bitbucket 服务器实例的 URL PROJECT | The key for the Bitbucket Server project of the repository you want to migrate CURRENT-NAME | The name of the repository you want to migrate 目标 | 目标组织的名称 NEW-NAME | 希望已迁移的存储库具有的名称 SSH-USER | 如果 Bitbucket 服务器实例在 Linux 上运行，则为通过 SSH 连接到 Bitbucket 服务器时使用的用户名 PATH-TO-KEY | 如果 Bitbucket 服务器实例在 Linux 上运行，则为 SSH 私钥的路径，例如 ~/.ssh/id_rsa。 有关 SSH 密钥的要求，请参阅“管理 GitHub Enterprise Importer 的访问权限”。 SMB-USER | 如果 Bitbucket Server 实例在 Windows 上运行，则为通过 SMB 连接到 Bitbucket Server 时使用的用户名 AWS-BUCKET-NAME | AWS S3 桶的桶名称

注意：如果收到提及 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-URL | Bitbucket 服务器实例的 URL PROJECT | The key for the Bitbucket Server project of the repository you want to migrate CURRENT-NAME | The name of the repository you want to migrate

将生成迁移存档，其路径将打印在命令输出中：

[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 \
  # 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 生成迁移脚本。 生成的脚本将包含迁移命令的列表（每个存储库一个）。

注意：生成脚本会输出 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 \
  # 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

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

将上述命令中的占位符替换为以下值。

占位符 | 值 | ----------- | ----- | BBS-SERVER-URL | Bitbucket 服务器实例的 URL 目标 | 目标组织的名称 FILENAME | 生成的迁移脚本的文件名

如果使用终端，请使用 .ps1 文件扩展名，因为生成的脚本需要 PowerShell 才能运行。 可以安装适用于 Mac 或 Linux 的 PowerShell。 SSH-USER | 如果 Bitbucket 服务器实例在 Linux 上运行，则为通过 SSH 连接到 Bitbucket 服务器时使用的用户名 PATH-TO-KEY | 如果 Bitbucket 服务器实例在 Linux 上运行，则为 SSH 私钥的路径，例如 ~/.ssh/id_rsa。 有关 SSH 密钥的要求，请参阅“管理 GitHub Enterprise Importer 的访问权限”。 SMB-USER | 如果 Bitbucket Server 实例在 Windows 上运行，则为通过 SMB 连接到 Bitbucket Server 时使用的用户名

查看迁移脚本

生成脚本后，查看文件，并根据需要编辑脚本。

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

运行迁移脚本

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

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

  • 通过 HTTPS 访问 Bitbucket Server 实例
  • 通过 SFTP 访问 Bitbucket Server 实例（如果 Bitbucket Server 实例在 Linux 上运行）。 通常，如果可以通过 SSH 访问该服务器，则也可以使用 SFTP。
  • 通过 SMB 访问 Bitbucket Server 实例（如果 Bitbucket Server 实例在 Windows 上运行）
  • 所选的 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 存储帐户的连接字符串。

Only connection strings using storage account access keys are supported. Connection strings which use shared access signatures (SAS) are not supported. For more information about storage account access keys, see Manage storage account access keys in the Azure documentation.

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

  • 如果使用终端，请使用 ./。
    Shell
    ./FILENAME
  • 如果使用 PowerShell，请使用 .\。
    Shell
    .\FILENAME