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

如果您选择使用 API，则需要编写自己的脚本或使用像 Insomnia 这样的 HTTP 客户端。您可以在“REST API 入门”和“使用 GraphQL 进行调用”中了解有关 GitHub API 入门的更多信息。

要使用 API 将您的仓库从 GitHub Enterprise Server 迁移到 GitHub Enterprise Cloud，您需要

1. 为源组织和目标组织创建个人访问令牌
2. 获取 GitHub Enterprise Cloud 上目标组织的 ownerId
3. 通过 GitHub.com 的 GraphQL API 设置迁移源，以标识您要迁移的来源
4. 对于您要迁移的每个仓库，重复以下步骤。
   • 使用 GitHub Enterprise Server 实例上的 REST API 为您的仓库生成迁移存档
   • 将迁移存档上传到 GitHub.com 可以访问的位置
   • 使用 GitHub.com 的 GraphQL API 启动迁移，传入您的存档 URL
   • 通过 GraphQL API 检查迁移状态
   • 验证迁移并检查错误日志

要查看使用 GitHub CLI 的说明，请使用页面顶部的工具切换器。

步骤 1. 创建您的个人访问令牌

1. 创建并记录一个将用于在 GitHub Enterprise Cloud 上对目标组织进行身份验证的个人访问令牌（经典），确保令牌满足所有要求。有关更多信息，请参阅“管理 GitHub 产品之间迁移的访问权限”。
2. 创建并记录一个将用于对源组织进行身份验证的个人访问令牌，确保此令牌也满足所有相同的要求。

步骤 2：获取目标组织的 ownerId

作为 GitHub Enterprise Cloud 中的组织所有者，使用 GetOrgInfo 查询返回 ownerId（也称为组织 ID），用于您想要拥有迁移存储库的组织。您需要 ownerId 来识别您的迁移目标。

GetOrgInfo 查询

query(
  $login: String!
){
  organization (login: $login)
  {
    login
    id
    name
    databaseId
  }
}

查询变量	描述
登录	您的组织名称。

GetOrgInfo 响应

{
  "data": {
    "organization": {
      "login": "Octo",
      "id": "MDEyOk9yZ2FuaXphdGlvbjU2MTA=",
      "name": "Octo-org",
      "databaseId": 5610
    }
  }
}

在本例中，MDEyOk9yZ2FuaXphdGlvbjU2MTA= 是组织 ID 或 ownerId，我们将在下一步中使用它。

步骤 3：设置 Blob 存储

由于许多 GitHub Enterprise Server 实例位于防火墙后面，对于 GitHub Enterprise Server 3.8 或更高版本，我们使用 Blob 存储作为中间位置来存储 GitHub 可以访问的数据。

您必须首先使用支持的云提供商设置 Blob 存储，然后在 GitHub Enterprise Server 实例的管理控制台中配置您的设置。

使用支持的云提供商设置 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/*"
            ]
        }
    ]
}

设置 Azure Blob 存储帐户

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

在 GitHub Enterprise Server 实例的管理控制台中配置 Blob 存储

设置 AWS S3 存储桶或 Azure Blob 存储存储帐户后，请在 GitHub Enterprise Server 实例的管理控制台中配置 Blob 存储。有关管理控制台的更多信息，请参阅“从管理控制台管理您的实例”。

1. 从 GitHub Enterprise Server 上的管理帐户，在任何页面右上角点击 .

2. 如果您尚未在“站点管理员”页面，请在左上角点击站点管理员。

3. 在“ 站点管理员”侧边栏中，点击管理控制台。

4. 登录管理控制台。

5. 在顶部导航栏中，点击设置。

6. 在迁移下，点击启用 GitHub 迁移。

7. 可选地，要导入您为 GitHub Actions 配置的存储设置，请选择从 Actions 复制存储设置。有关更多信息，请参阅“使用 Azure Blob 存储启用 GitHub Actions”和“使用 Amazon S3 存储启用 GitHub Actions”。

   注意：复制存储设置后，您可能仍然需要更新云存储帐户的配置才能与 GitHub Enterprise Importer 配合使用。特别是，您必须确保 GitHub 的 IP 地址已列入白名单。有关更多信息，请参阅“管理 GitHub 产品之间迁移的访问权限”。

8. 如果您没有从 GitHub Actions 导入存储设置，请选择Azure Blob 存储或Amazon S3，并填写所需的详细信息。

   注意：如果您使用 Amazon S3，则必须将“AWS 服务 URL”设置为存储桶所在的 AWS 区域的标准端点。例如，如果您的存储桶位于eu-west-1区域，则“AWS 服务 URL”将为https://s3.eu-west-1.amazonaws.com。您的 GitHub Enterprise Server 实例的网络必须允许访问此主机。不支持网关端点，例如bucket.vpce-0e25b8cdd720f900e-argc85vg.s3.eu-west-1.vpce.amazonaws.com。有关网关端点的更多信息，请参阅 AWS 文档中的Amazon S3 的网关端点。

9. 点击测试存储设置。

10. 点击保存设置。

步骤 4：在 GitHub Enterprise Cloud 中设置迁移源

您可以使用 createMigrationSource 查询设置迁移源。您需要提供从 GetOrgInfo 查询中获取的 ownerId 或组织 ID。

您的迁移源是您在 GitHub Enterprise Server 上的组织。

createMigrationSource 变异

mutation createMigrationSource($name: String!, $url: String!, $ownerId: ID!) {
  createMigrationSource(input: {name: $name, url: $url, ownerId: $ownerId, type: GITHUB_ARCHIVE}) {
    migrationSource {
      id
      name
      url
      type
    }
  }
}

查询变量	描述
name	迁移源的名称。此名称仅供您自己参考，因此您可以使用任何字符串。
ownerId	您在 GitHub Enterprise Cloud 上的组织的组织 ID。
url	GitHub Enterprise Server 实例的 URL。此 URL 无需从 GitHub Enterprise Cloud 访问。

createMigrationSource 响应

{
  "data": {
    "createMigrationSource": {
      "migrationSource": {
        "id": "MS_kgDaACRjZTY5NGQ1OC1mNDkyLTQ2NjgtOGE1NS00MGUxYTdlZmQwNWQ",
        "name": "GHES Source",
        "url": "https://my-ghes-hostname.com",
        "type": "GITHUB_ARCHIVE"
      }
    }
  }
}

在此示例中，MS_kgDaACRjZTY5NGQ1OC1mNDkyLTQ2NjgtOGE1NS00MGUxYTdlZmQwNWQ 是迁移源 ID，我们将在后面的步骤中使用它。

步骤 5：在您的 GitHub Enterprise Server 实例上生成迁移存档

您将使用 REST API 在 GitHub Enterprise Server 中启动两个“迁移”：一个用于生成存储库 Git 源的存档，另一个用于生成存储库元数据（如问题和拉取请求）的存档。

要生成 Git 源存档，请向 https://HOSTNAME/api/v3/orgs/ORGANIZATION/migrations 发出 POST 请求，将 HOSTNAME 替换为 GitHub Enterprise Server 实例的主机名，将 ORGANIZATION 替换为您的组织的登录名。

在正文中，指定您要迁移的单个存储库。您的请求将类似于以下内容

POST /api/v3/orgs/acme-corp/migrations HTTP/1.1
Accept: application/vnd.github+json
Authorization: Bearer <TOKEN>
Content-Type: application/json
Host: github.acmecorp.net

{
  "repositories": ["repository_to_migrate"],
  "exclude_metadata": true
}

要生成元数据存档，请向同一 URL 发送类似的请求，并使用以下正文

{
  "repositories": ["repository_to_migrate"],
  "exclude_git_data": true,
  "exclude_releases": false,
  "exclude_owner_projects": true
}

这两个 API 调用中的每一个都将返回一个 JSON 响应，其中包含您已启动的迁移的 ID。

HTTP/1.1 201 Created

{
  "id": 123,
  // ...
}

有关更多信息，请参阅“启动组织迁移”。

生成归档可能需要一段时间，具体取决于数据量。您可以定期使用“获取组织迁移状态”API 检查两次迁移的状态，直到迁移的state变为exported。

GET /api/v3/orgs/acme-corp/migrations/123 HTTP/1.1
Accept: application/vnd.github+json
Authorization: Bearer <TOKEN>
Host: github.acmecorp.net

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 123,
  "state": "exported",
  // ...
}

有关更多信息，请参阅“获取组织迁移状态”。

在迁移的state变为exported后，您可以使用“下载组织迁移归档”API 获取迁移的 URL。

GET /api/v3/orgs/acme-corp/migrations/123/archive HTTP/1.1
Accept: application/vnd.github+json
Authorization: Bearer <TOKEN>
Host: github.acmecorp.net

HTTP/1.1 302 Found
Location: https://media.github.acmecorp.net/migrations/123/archive/cca2ebe9-7403-4ffa-9b6a-4c9e16c94410?token=AAAAABEWE7JP4H2HACKEGMTDOYRC6

API 将返回一个302 Found响应，其中包含一个Location标头，该标头将重定向到可下载归档所在的 URL。下载两个文件：一个用于 Git 源代码，另一个用于元数据。

有关更多信息，请参阅“下载组织迁移归档”。

在两次迁移都完成并且您下载了归档后，您可以转到下一步。

步骤 6：上传您的迁移归档

要将您的数据导入 GitHub Enterprise Cloud，您必须使用我们的 GraphQL API 将每个存储库的两个归档（Git 源代码和元数据）从您的机器传递到 GitHub.com。

如果您使用的是 GitHub Enterprise Server 3.7 或更低版本，您必须首先为 GitHub.com 可访问的归档生成 URL。大多数客户选择将归档上传到云提供商的 Blob 存储服务（例如 Amazon S3 或 Azure Blob Storage），然后为每个归档生成一个短期 URL。

如果您使用的是 GitHub Enterprise Server 3.8 或更高版本，您的实例会为您上传存档并生成 URL。 上一步中的 Location 标头将返回短期 URL。

您可能需要将 GitHub 的 IP 范围列入白名单。 有关更多信息，请参阅“管理 GitHub 产品之间迁移的访问权限”。

步骤 7：启动您的仓库迁移

启动迁移时，单个仓库及其附带的数据将迁移到您指定的全新 GitHub 仓库中。

如果您想一次从同一个源组织迁移多个仓库，您可以排队多个迁移。 您可以同时运行最多 5 个仓库迁移。

startRepositoryMigration 突变

mutation startRepositoryMigration (
  $sourceId: ID!,
  $ownerId: ID!,
  $repositoryName: String!,
  $continueOnError: Boolean!,
  $accessToken: String!,
  $githubPat: String!,
  $gitArchiveUrl: String!,
  $metadataArchiveUrl: String!,
  $sourceRepositoryUrl: URI!,
  $targetRepoVisibility: String!
){
  startRepositoryMigration( input: {
    sourceId: $sourceId,
    ownerId: $ownerId,
    repositoryName: $repositoryName,
    continueOnError: $continueOnError,
    accessToken: $accessToken,
    githubPat: $githubPat,
    targetRepoVisibility: $targetRepoVisibility
    gitArchiveUrl: $gitArchiveUrl,
    metadataArchiveUrl: $metadataArchiveUrl,
    sourceRepositoryUrl: $sourceRepositoryUrl,
  }) {
    repositoryMigration {
      id
      migrationSource {
        id
        name
        type
      }
      sourceUrl
    }
  }
}

查询变量	描述
sourceId	从 createMigrationSource 突变返回的迁移源 id。
ownerId	您在 GitHub Enterprise Cloud 上的组织的组织 ID。
repositoryName	自定义的唯一仓库名称，目前未被您在 GitHub Enterprise Cloud 上拥有的任何组织的仓库使用。 当您的迁移完成或停止时，将在该仓库中创建错误日志问题。
continueOnError	迁移设置，允许迁移在遇到不会导致迁移失败的错误时继续。 必须为 true 或 false。 我们强烈建议将 continueOnError 设置为 true，以便您的迁移将继续，除非 Importer 无法移动 Git 源代码，或者 Importer 已经断开连接并且无法重新连接以完成迁移。
githubPat	您在 GitHub Enterprise Cloud 上的目标组织的个人访问令牌。
accessToken	您源的个人访问令牌。
targetRepoVisibility	新仓库的可见性。 必须为 private、public 或 internal。 如果未设置，您的仓库将以私有方式迁移。
gitArchiveUrl	您 Git 源代码存档的 GitHub Enterprise Cloud 可访问 URL。
metadataArchiveUrl	您元数据存档的 GitHub Enterprise Cloud 可访问 URL。
sourceRepositoryUrl	您在 GitHub Enterprise Server 实例上的仓库的 URL。 这是必需的，但 GitHub Enterprise Cloud 不会直接与您的 GitHub Enterprise Server 实例通信。

有关个人访问令牌要求，请参阅“管理 GitHub 产品之间迁移的访问权限”。

在下一步中，您将使用从 startRepositoryMigration 变异返回的迁移 ID 来检查迁移状态。

步骤 8：检查迁移状态

为了检测任何迁移失败并确保您的迁移正常工作，您可以使用 getMigration 查询检查您的迁移状态。您也可以使用 getMigrations 检查多个迁移的状态。

getMigration 查询将返回一个状态，让您知道迁移是 queued、in progress、failed 还是 completed。如果您的迁移失败，Importer 将提供失败的原因。

getMigration 查询

query (
  $id: ID!
){
  node( id: $id ) {
    ... on Migration {
      id
      sourceUrl
      migrationSource {
        name
      }
      state
      failureReason
    }
  }
}

查询变量	描述
id	您的迁移的 id，由 startRepositoryMigration 变异 返回。

步骤 9：验证您的迁移并检查错误日志

为了完成您的迁移，我们建议您检查“迁移日志”问题。此问题是在目标存储库的 GitHub 中创建的。

最后，我们建议您审查您迁移的存储库以进行健全性检查。

gh extension upgrade github/gh-gei

{
    "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/*"
            ]
        }
    ]
}

gh gei generate-script --github-source-org SOURCE \
  --github-target-org DESTINATION \
  --output FILENAME \
  --ghes-api-url GHES-API-URL

gh gei generate-script --github-source-org SOURCE \
  --github-target-org DESTINATION \
  --output FILENAME \
  --ghes-api-url GHES-API-URL

gh gei generate-script --github-source-org SOURCE \
  --github-target-org DESTINATION \
  --output FILENAME \
  --ghes-api-url GHES-API-URL \
  --aws-bucket-name AWS-BUCKET-NAME

gh gei generate-script --github-source-org SOURCE \
  --github-target-org DESTINATION \
  --output FILENAME \
  --ghes-api-url GHES-API-URL \
  --aws-bucket-name AWS-BUCKET-NAME

gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME --ghes-api-url GHES-API-URL

gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME --ghes-api-url GHES-API-URL

gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME \
    --ghes-api-url GHES-API-URL --azure-storage-connection-string "AZURE_STORAGE_CONNECTION_STRING"

gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME \
    --ghes-api-url GHES-API-URL --azure-storage-connection-string "AZURE_STORAGE_CONNECTION_STRING"

gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME \
    --ghes-api-url GHES-API-URL --aws-bucket-name "AWS-BUCKET-NAME"

gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME \
    --ghes-api-url GHES-API-URL --aws-bucket-name "AWS-BUCKET-NAME"

gh gei abort-migration --migration-id MIGRATION-ID

gh gei abort-migration --migration-id MIGRATION-ID