关于使用 GitHub Enterprise Importer
进行存储库迁移
可以使用 GitHub CLI 从 BitBucket Server 实例迁移单个存储库或所有存储库。
目前,不支持使用 GitHub API 从 Bitbucket Server 迁移。
Note
如果要迁移的存储库具有与传入存储库不匹配的规则集,则迁移将被阻止。 若要绕过这些规则集并允许迁移,可以对目标组织中的所有部署密钥应用规则集绕过。
可以在组织级别设置存储库规则集。 如果传入存储库与这些规则集中的任何一个都不匹配,则需要对每个规则集使用部署密钥绕过。 请参阅“创建组织中存储库的规则集”。
先决条件
- 强烈建议执行迁移的试运行,然后在不久之后完成生产迁移。 要了解试运行的详细信息,请参阅“从 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
。
-
安装 GitHub CLI。 有关 GitHub CLI 的安装说明,请参阅 GitHub CLI 存储库。
注意:需要 GitHub CLI 版本 2.4.0 或更高版本。 可以使用
gh --version
命令检查已安装的版本。 -
安装 BBS2GH extension。
Shell gh extension install github/gh-bbs2gh
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 每周更新一次。 为了确保使用的是最新版本,请更新扩展。
gh extension upgrade github/gh-bbs2gh
gh extension upgrade github/gh-bbs2gh
步骤 3:设置环境变量
在使用 BBS2GH extension 迁移到 GitHub Enterprise Cloud 之前,必须创建可以访问目标组织的 personal access token,然后将 personal access token 设置为环境变量。
还需要为 Bitbucket Server 用户名和密码设置环境变量,如果 Bitbucket Server 实例在 Windows 上运行,则还需要为 SMB 密码设置环境变量。
-
创建并记录一个 personal access token (classic),用于在 GitHub Enterprise Cloud 上为目标组织进行身份验证,确保令牌满足所有要求。 有关详细信息,请参阅“管理从 Bitbucket Server 迁移的访问权限”。
-
设置环境变量,将 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"
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"
-
步骤 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
的环境变量将其传入。
步骤 5:迁移存储库
你可以使用 gh bbs2gh migrate-repo
命令迁移存储库。
迁移存储库时,BBS2GH extension of the GitHub CLI 默认将执行以下步骤:
- 连接到 Bitbucket Server 实例并为每个存储库生成迁移存档
- 使用 SFTP (Linux) 或 SMB (Windows),将迁移存档从 Bitbucket Server 实例下载到运行 BBS2GH extension of the GitHub CLI 的计算机
- 将迁移存档上传到所选的 blob 存储提供程序
- 通过使用 blob 存储提供程序存储的存档 URL 在 GitHub Enterprise Cloud 中开始迁移
- 从本地计算机中删除迁移存档。 (迁移完成后,需要手动从 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 存储提供程序
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
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 服务器实例的 URL |
PROJECT | 要迁移的存储库的 Bitbucket Server 项目的密钥 |
CURRENT-NAME | 要迁移的存储库的名称 |
目标 | 目标组织的名称 |
NEW-NAME | 希望已迁移的存储库具有的名称 |
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-NAME | AWS 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
命令:
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 服务器实例的 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
命令:
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
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 迁移存档的路径 |
目标 | 目标组织的名称 |
NEW-NAME | 希望已迁移的存储库具有的名称 |
BBS-SERVER-URL | Bitbucket 服务器实例的 URL |
PROJECT | 要迁移的存储库的 Bitbucket Server 项目的密钥 |
CURRENT-NAME | 要迁移的存储库的名称 |
AWS-BUCKET-NAME | AWS S3 桶的桶名称 |
取消迁移
如果要取消迁移,请使用 abort-migration
命令,将 MIGRATION-ID 替换为从 migrate-repo
返回的 ID。
gh bb2gh abort-migration --migration-id MIGRATION-ID
gh bb2gh abort-migration --migration-id MIGRATION-ID
步骤 6:验证迁移并检查错误日志
迁移完成后,建议查看迁移日志。 有关详细信息,请参阅“访问 GitHub Enterprise Importer 的迁移日志”。
建议查看已迁移的存储库以进行完整性检查。
步骤 7:迁移多个存储库
如果要一次性将多个存储库迁移到 GitHub Enterprise Cloud,请使用 GitHub CLI 生成迁移脚本。 生成的脚本将包含迁移命令的列表(每个存储库一个)。
生成迁移脚本
必须在可通过 HTTPS 访问 Bitbucket Server 实例的计算机上执行此步骤。
若要生成迁移脚本,请运行 gh bbs2gh generate-script
命令。
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
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 服务器实例的 URL |
目标 | 目标组织的名称 |
FILENAME | 生成的迁移脚本的文件名 如果使用终端,请使用 .ps1 文件扩展名,因为生成的脚本需要 PowerShell 才能运行。 可以安装适用于 Mac 或 Linux 的 PowerShell。 |
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
:存储桶的访问密钥 IDAWS_SECRET_ACCESS_KEY
:存储桶的密钥AWS_REGION
:桶所在的 AWS 区域AWS_SESSION_TOKEN
:会话令牌(如果使用的是 AWS 临时凭据)(请参阅 AWS 文档中的将临时凭据用于 AWS 资源)
- 对于 Azure Blob 存储,请将
AZURE_STORAGE_CONNECTION_STRING
设置为 Azure 存储帐户的连接字符串。
仅支持使用存储帐户访问密钥的连接字符串。 不支持使用共享访问签名 (SAS) 的连接字符串。 有关存储帐户访问密钥的详细信息,请参阅 Azure 文档中的管理存储帐户访问密钥。
要迁移多个存储库,请运行上面生成的脚本。 将以下命令中的 FILENAME 替换为生成脚本时提供的文件名。
-
如果使用终端,请使用
./
。Shell ./FILENAME
./FILENAME
-
如果使用 PowerShell,请使用
.\
。Shell .\FILENAME
.\FILENAME