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

If you choose to use the API, you'll need to write your own scripts or use an HTTP client like Insomnia. You can learn more about getting started with GitHub's APIs in Getting started with the REST API and Forming calls with GraphQL.

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

1. 为源组织和目标组织创建个人访问令牌
2. 获取 GitHub Enterprise Cloud 上目标组织的 ownerId
3. 通过 GitHub 的 GraphQL API 设置迁移源，以标识迁移的来源
4. 对每个想要迁移的仓库，重复以下步骤。
   • 在你的 GitHub Enterprise Server 实例上使用 REST API 为仓库生成迁移归档
   • 将迁移归档上传到 GitHub 能访问的位置
   • 使用目标方的 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 Importer 可以访问的位置。这可以通过以下方式实现：

• 使用 GHES 实例上的本地存储（GHES 3.16 及以上）
• 使用 Blob 存储提供商

使用本地存储（GHES 3.16+）

使用本地存储运行迁移时，归档数据会写入 GitHub Enterprise Server 实例的磁盘，无需云存储提供商。

• 如果没有防火墙规则阻止 GitHub Enterprise Server 的出站流量，GitHub Enterprise Importer 可以自动从 GitHub Enterprise Server 检索已存储的归档。
• 如果已设置防火墙规则且不希望允许 GitHub Enterprise Importer 访问，你可以将归档数据上传到 GitHub 拥有的 Blob 存储，以供 GitHub Enterprise Importer 访问。要手动执行此操作，请参阅本文 API 版本中的 Uploading your migration archives to GitHub-owned blob storage。

1. 在 GitHub Enterprise Server 的管理账户上，任意页面的右上角，点击.
2. 在 "Site admin\" 侧边栏，点击 Management Console。
3. 登录管理控制台。
4. 在左侧边栏，点击 Migrations。
5. 点击 Enable GitHub Migrations。
6. 在 “Migrations Storage” 下，点击 Local Storage。
7. 点击 Save settings。

执行迁移时，请监控 GitHub Enterprise Server 的磁盘空间。迁移归档会在 7 天后自动删除。若要释放空间，你可以使用 REST API 端点（组织迁移） 删除归档。

使用 Blob 存储提供商

如果你的 GitHub Enterprise Server 实例位于防火墙后，可能需要使用外部云服务来设置 Blob 存储。

首先，需要使用受支持的提供商设置 Blob 存储。随后，如果使用云提供商，则必须在管理控制台或 GitHub CLI 中配置该存储提供商的凭据。

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

• Amazon Web Services（AWS）S3
• Azure Blob Storage

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

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

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

在设置好 AWS S3 存储桶或 Azure Blob Storage 账户后，需要在 GitHub Enterprise Server 实例的管理控制台中配置 Blob 存储。有关管理控制台的更多信息，请参阅 Administering your instance from the Management Console。

1. 在 GitHub Enterprise Server 的管理账户上，任意页面的右上角，点击.

2. 如果尚未在 “Site admin” 页面，左上角点击 Site admin。

3. 在 "Site admin\" 侧边栏，点击 Management Console。

4. 登录管理控制台。

5. 在顶部导航栏，点击 Settings。

6. 在 Migrations 下，点击 Enable GitHub Migrations。

7. 可选地，若要导入为 GitHub Actions 配置的存储设置，选择 Copy Storage settings from Actions。更多信息请参阅 Enabling GitHub Actions with Azure Blob storage 与 Enabling GitHub Actions with Amazon S3 storage。

   注意

   复制存储设置后，仍可能需要更新云存储账户的配置，以便与 GitHub Enterprise Importer 配合使用。尤其要确保已将 GitHub 的 IP 地址列入白名单。更多信息请参阅 Managing access for a migration between GitHub products。

8. 如果未从 GitHub Actions 导入存储设置，请选择 Azure Blob Storage 或 Amazon S3 并填写必填信息。

   注意

   如果使用 Amazon S3，则必须将 “AWS Service URL” 设置为存放桶所在 AWS 区域的标准终端。例如，若桶位于 eu-west-1 区域，则 “AWS Service URL” 为 https://s3.eu-west-1.amazonaws.com。你的 GitHub Enterprise Server 实例网络必须能够访问此主机。网关终端（gateway endpoints）不受支持，例如 bucket.vpce-0e25b8cdd720f900e-argc85vg.s3.eu-west-1.vpce.amazonaws.com。有关网关终端的更多信息，请参阅 AWS 文档中的 Gateway endpoints for Amazon S3。

9. 点击 Test storage settings。

10. 点击 Save settings。

允许网络访问

如果在存储账户上配置了防火墙规则，请确保已允许迁移目标的 IP 段访问。参见 Managing access for a migration between GitHub products。

步骤 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
    }
  }
}

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 源的归档，另一项生成仓库元数据（如 Issue 和 Pull Request）的归档。

要生成 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 调用各会返回包含已启动迁移 ID 的 JSON 响应。

HTTP/1.1 201 Created

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

更多信息请参阅 Start an organization migration。

生成归档可能需要一些时间，取决于数据量。你可以使用 “Get an organization migration status” 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",
  // ...
}

更多信息请参阅 Get an organization migration status。

当迁移的 state 变为 exported 后，可使用 “Download an organization migration archive” 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 源，另一个为元数据。

更多信息请参阅 Download an organization migration archive。

在两个迁移完成并下载归档后，可进入下一步。

步骤 6：上传迁移归档

要将数据导入 GitHub Enterprise Cloud，必须使用我们的 GraphQL API 将每个仓库的两个归档（Git 源和元数据）从本地机器传输至 GitHub。

如果使用 GitHub Enterprise Server 3.7 或更低版本，需先生成 GitHub 可访问的归档 URL。大多数客户会将归档上传至云提供商的 Blob 存储服务（如 Amazon S3 或 Azure Blob Storage），然后为每个归档生成短期 URL。

如果使用 GitHub Enterprise Server 3.8 或更高版本，实例会自行上传归档并生成 URL。上一步的 Location 头部会返回该短期 URL。

可能需要将 GitHub 的 IP 段列入白名单。更多信息请参阅 Managing access for a migration between GitHub products。

将迁移归档上传至 GitHub 拥有的 Blob 存储

如果使用 GitHub 拥有的 Blob 存储，你将按照以下流程将归档上传至该存储

1. 通过提交 POST 请求创建分段上传（multipart upload）
2. 使用 PATCH 请求将归档分为最多 100MB 的多个部分上传
3. 提交 PUT 请求完成上传

1. 创建分段上传

你将向以下地址提交 POST 请求

https://uploads.github.com/organizations/{organization_id}/gei/archive/blobs/uploads

在请求体中包含如下 JSON，注明归档名称和大小。所有上传的 Content-Type 均可保持为 "application/octet-stream"。

{
"content_type": "application/octet-stream",
"name": "git-archive.tar.gz",
"size": 262144000
}

这将返回如下 JSON 对象响应

{
  "guid": "363b2659-b8a3-4878-bfff-eed4bcb54d35",
  "node_id": "MA_kgDaACQzNjNiMjY1OS1iOGEzLTQ4NzgtYmZmZi1lZWQ0YmNiNTRkMzU",
  "name": "git-archive.tar.gz",
  "size": 33287,
  "uri": "gei://archive/363b2659-b8a3-4878-bfff-eed4bcb54d35",
  "created_at": "2024-11-13T12:35:45.761-08:00"
}

该 URI 代表已上传的归档，在启动仓库迁移时将用于排队迁移。响应还会在响应头中提供用于下一步使用 PATCH 请求上传文件分片的 location。

/organizations/{organization_id}/gei/archive/blobs/uploads?part_number=1&guid=<guid>&upload_id=<upload_id>

2. 分段上传归档

使用先前响应头中提供的 location，使用 PATCH 请求每次上传最多 100 MB 的文件部分，确保原始数据直接放在请求体中，不使用 multipart form。如果文件的最后一部分不足 100 MB，则仅在最后一次请求中上传剩余字节。

https://uploads.github.com/{location}

这将返回空响应体，并在响应头中提供以下 location

/organizations/{organization_id}/gei/archive/blobs/uploads?part_number=2&guid=<guid>&upload_id=<upload_id>

重复以上步骤直至上传完成。每次读取最多 100 MB 的文件，并使用递增的 part_number 值将请求发送至新返回的 location。

3. 完成上传

向上一部中返回的 “last path” 值提交一个空体的 PUT 请求，即完成对 GitHub 拥有存储的上传。GEI URI 可使用此初始 POST 请求返回的 GUID 按以下格式构造

gei://archive/{guid}

步骤 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
    }
  }
}

有关个人访问令牌的要求，请参阅 管理 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
    }
  }
}

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

要完成迁移，我们建议您检查 “Migration Log” issue。该 issue 会在目标仓库的 GitHub 中创建。

最后，建议您检查已迁移的仓库，以确保其完整性。