从 Bitbucket Server 迁移仓库至 GitHub Enterprise Cloud - GitHub 文档

关于使用 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 前缀。

安装 GitHub CLI。有关 GitHub CLI 的安装说明，请参阅 GitHub CLI 仓库。

注意

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

安装 BBS2GH 扩展。

Shell

gh extension install github/gh-bbs2gh

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

gh extension upgrade github/gh-bbs2gh

步骤 3：设置环境变量

在使用 BBS2GH 扩展迁移至 GitHub Enterprise Cloud 之前，您必须创建一个能够访问目标组织的个人访问令牌（Personal Access Token），并将该令牌设置为环境变量。

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

创建并记录一个（经典）个人访问令牌（Personal Access Token），用于在 GitHub Enterprise Cloud 上对目标组织进行身份验证，并确保该令牌满足所有要求。更多信息，请参阅《管理 Bitbucket Server 迁移的访问权限》。

设置环境变量，将 TOKEN 替换为您上面记录的个人访问令牌，将 USERNAME 替换为具有管理员或超级管理员权限的 Bitbucket Server 帐户用户名，将 PASSWORD 替换为该 Bitbucket Server 帐户的密码。

如果您使用 Terminal，请使用 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"

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"

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

如果您正在迁移到具有数据驻留的 GitHub Enterprise Cloud，为方便起见，请为您企业的 基础 API URL 设置环境变量。

确保将 SUBDOMAIN 替换为您企业的子域。例如，如果企业子域为 acme，则 TARGET_API_URL 的值应为 https://api.acme.ghe.com。
- 如果您使用 Terminal，请使用 export 命令。
  Shell
```
export TARGET_API_URL="https://api.SUBDOMAIN.ghe.com"
```
```
export TARGET_API_URL="https://api.SUBDOMAIN.ghe.com"
```
- 如果您使用 PowerShell，请使用 $env 命令。
  Shell
```
$env:TARGET_API_URL="https://api.SUBDOMAIN.ghe.com"
```
```
$env:TARGET_API_URL="https://api.SUBDOMAIN.ghe.com"
```
您将在使用 GitHub CLI 运行的命令中，通过 --target-api-url 选项使用此变量。

步骤 4：设置 Blob 存储

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

您将首先生成要迁移的数据归档，然后从防火墙内部将其推送至 Blob 存储。

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

Amazon Web Services（AWS）S3
Azure Blob Storage

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

使用 GitHub 托管的 Blob 存储

如果您不想在防火墙后设置并向 GitHub Enterprise Importer 提供 Blob 存储账户的访问权限，可以使用 --use-github-storage 标志，通过 GitHub 托管的 Blob 存储进行仓库迁移。为此，您必须使用 BBS2GH 扩展的 v1.9.0（或更高）版本。

出于安全考虑，GitHub 托管的 Blob 存储仅限写入，无法下载。迁移完成后，仓库归档会立即被删除。如果归档已上传但未在迁移中使用，则该归档将在 7 天后被删除。

设置 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 Storage 存储账户

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

注意

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

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

允许网络访问

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

步骤 5：迁移仓库

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

迁移仓库时，默认情况下，GitHub CLI 的 BBS2GH 扩展会执行以下步骤

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

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

允许 GitHub CLI 下载迁移归档
手动下载迁移归档

允许 GitHub CLI 下载迁移归档

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

您必须在能够访问以下内容的计算机上执行此步骤

您的 Bitbucket Server 实例（通过 HTTPS）
您的 Bitbucket Server 实例（通过 SFTP），如果您的 Bitbucket Server 实例运行在 Linux 上。一般来说，只要能通过 SSH 访问服务器，就可以使用 SFTP。
您的 Bitbucket Server 实例（通过 SMB），如果您的 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 are 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
  # If you are using GitHub owned blob storage:
  --use-github-storage

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 are 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
  # If you are using GitHub owned blob storage:
  --use-github-storage

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

占位符	值
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 迁移的访问权限》。
SMB-USER	如果您的 Bitbucket Server 实例运行在 Windows 上，则在通过 SMB 连接到 Bitbucket Server 时使用的用户名
AWS-BUCKET-NAME	您 AWS S3 存储桶的名称
ARCHIVE-DOWNLOAD-HOST	用于通过 SSH 或 SMB 连接到 Bitbucket Server/Data Center 实例的主机。如果您运行的是 Bitbucket 数据中心集群或 Bitbucket Server 位于负载均衡器后面，则需要指定此项。

注意

如果出现提及 Renci.SshNet 的错误，则 CLI 在与服务器建立 SFTP 连接以下载迁移归档时遇到问题。有关如何排查这些问题的信息，请参阅《使用 GitHub Enterprise Importer 进行迁移的故障排除》。

手动下载迁移归档

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

然而，一些客户更倾向于手动下载迁移归档，例如因为服务器不提供 SFTP 访问。此时，您可以使用 GitHub CLI 生成归档，手动下载该归档，然后再使用 GitHub CLI 继续迁移。

您必须在能够访问以下内容的计算机上执行此步骤

您的 Bitbucket Server 实例（通过 HTTPS）
您选择的 Blob 存储提供商

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

Shell

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

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 are 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

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 are 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 bbs2gh abort-migration --migration-id MIGRATION-ID

gh bbs2gh 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
  # If you are using GitHub owned blob storage:
  --use-github-storage

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
  # If you are using GitHub owned blob storage:
  --use-github-storage

如果希望脚本下载每个迁移仓库的迁移日志，请添加 --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 迁移的访问权限》。
SMB-USER	如果您的 Bitbucket Server 实例运行在 Windows 上，则在通过 SMB 连接到 Bitbucket Server 时使用的用户名
ARCHIVE-DOWNLOAD-HOST	用于通过 SSH 或 SMB 连接到 Bitbucket Server/Data Center 实例的主机。如果您运行的是 Bitbucket 数据中心集群或 Bitbucket Server 位于负载均衡器后面，则需要指定此项。

审查迁移脚本

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

如果有不想迁移的仓库，请删除或注释掉相应的行。
默认情况下，GitHub 中的仓库名称遵循 projectKey-repositoryName 约定。例如，位于项目 open-source（键为 OS）中的 Bitbucket Server 仓库 airports，在 GitHub 中将命名为 OS-airports。如果希望某些仓库在 GitHub 中使用不同的名称，请为相应的 --github-repo 标志更新值。

如果您下载的是独立二进制文件而非 GitHub CLI 的扩展，则需要将生成的脚本修改为运行该二进制文件，而不是 gh bbs2gh。

运行迁移脚本

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

您必须在能够访问以下内容的计算机上执行此步骤

您的 Bitbucket Server 实例（通过 HTTPS）
您的 Bitbucket Server 实例（通过 SFTP），如果您的 Bitbucket Server 实例运行在 Linux 上。一般来说，只要能通过 SSH 访问服务器，就可以使用 SFTP。
您的 Bitbucket Server 实例（通过 SMB），如果您的 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 Storage，请将 AZURE_STORAGE_CONNECTION_STRING 设置为您 Azure 存储账户的连接字符串。

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

要迁移多个仓库，请运行您生成的脚本。将以下命令中的 FILENAME 替换为生成脚本时指定的文件名。

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

将仓库从 Bitbucket Server 迁移到 GitHub Enterprise Cloud

本文内容

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

先决条件

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

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

步骤 3：设置环境变量

步骤 4：设置 Blob 存储

使用 GitHub 托管的 Blob 存储

设置 AWS S3 存储桶

设置 Azure Blob Storage 存储账户

允许网络访问

步骤 5：迁移仓库

允许 GitHub CLI 下载迁移归档

手动下载迁移归档

取消迁移

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

步骤 7：迁移多个仓库

生成迁移脚本

审查迁移脚本

运行迁移脚本