迁移GitHub Actions外部存储

关于迁移 GitHub Actions 外部存储

合并云帐户、满足驻留要求或重新组织存储租赁时，可以将外部存储迁移到 GitHub Actions 同一提供程序上的新存储桶、帐户或区域。

该迁移之所以可行，是因为 GitHub Actions 根据存储桶或容器中对象的键（路径）来识别存储对象，而不是根据存储桶或账户名称。 只要保留内部密钥布局并更新配置以指向新位置，现有工作流日志和项目将保持可访问状态，而不会中断。

Considerations

在开始之前，请查看以下约束。 每一项都会影响迁移方法，而其中有几项如果被忽略，可能会导致数据丢失。

• 仅限同一提供程序。 此过程支持在同一存储提供程序类型（例如 Amazon S3 到 Amazon S3、Azure Blob 到 Azure Blob、Google Cloud Storage 到 Google Cloud Storage 或 MinIO 到 MinIO）中进行迁移。 此处不涵盖跨提供商迁移。 如需进行跨服务提供商迁移，请联系 GitHub Enterprise 支持。
• 在迁移过程中不要更改身份验证方法。 如果当前使用基于凭据的身份验证，则目标配置还必须使用基于凭据的身份验证。 这同样适用于 OpenID Connect。 在存储配置更改期间切换身份验证方法可能会导致数据丢失。 有关详细信息，请参阅“更新 GitHub Actions 存储的凭据”。 若要更改身份验证方法，请先完成存储迁移，然后规划单独的更改。
• 必须保留存储桶或容器内的键布局。 源存储桶或容器内的对象键（路径）在目标上必须保持不变。 目标存储桶名称、存储帐户、区域和其他连接参数可能会更改。 在切换时于 管理控制台 中更新这些。 大多数提供商原生复制工具在复制整个存储桶或容器时会自动保留键布局，但在正式切换前，请确认目标端与源端一致。
• GitHub Packages 具有其他约束。 如果还使用 GitHub Packages，请参阅 GitHub Packages 下面的注意事项 部分，然后再开始。

先决条件

• 您拥有对 你的 GitHub Enterprise Server 实例 的站点管理员访问权限。
• 您已在所需的帐户、区域或租户中，在与源端相同的提供商上预配了目标存储资源。
• 目的地为空。
• 目标授予 你的 GitHub Enterprise Server 实例 与源相同的权限。 有关所需权限，请参阅相关配置文章：
  • 使用 Amazon S3 存储启用 GitHub Actions
  • 使用 Azure Blob 存储启用GitHub Actions
  • 使用 Google Cloud Storage 启用 GitHub Actions
  • 使用 MinIO 存储启用 GitHub Actions
• 你拥有源和目标存储的管理凭据，足以读取所有源对象并写入目标。
• 你有 你的 GitHub Enterprise Server 实例 的最新备份。 有关详细信息，请参阅“使用备份实用工具在实例上配置备份”。
• 您已在预发布环境中进行过迁移演练。 请参阅下一部分。

在过渡环境中排练迁移

在生产环境中执行迁移之前，请先在预发布实例上完整演练整个流程。 基于最近的生产备份预配一个暂存 GitHub Enterprise Server 实例，将其指向一个与预期生产目标保持一致的临时目标，并将本文中的每个步骤从头到尾完整执行一遍。 有关详细信息，请参阅 设置暂存实例 和 使用暂存环境。

预演环境演练验证以下内容：

• 目标端的提供程序端权限、网络访问和策略均已正确配置。
• 你选择的复制工具能够在具有代表性的数据量下成功完成复制。
• 源端和目标端的预期对象数量及总大小一致。
• 切换完成后，可通过 UI 获取现有工作流的运行日志和制品。

执行迁移

按顺序完成以下步骤。 GitHub Actions 可以继续为流量提供服务，直到启用维护模式。

1. 执行初始数据复制。 使用提供程序原生工具将所有对象从源复制到目标。 在复制过程中写入源端的新对象，将在切换后的最终增量同步中被捕获。

   使用示例命令作为起点。 请参阅上游文档，了解完整的选项集，包括凭据、加密和吞吐量优化。

   对于 Amazon S3，请使用 aws s3 sync AWS 命令行���口。 首先运行试运行以验证操作，然后执行复制。

   aws s3 sync s3://SOURCE-BUCKET s3://DESTINATION-BUCKET --dryrun
   aws s3 sync s3://SOURCE-BUCKET s3://DESTINATION-BUCKET
   

   对于Azure Blob 存储，请azcopy copy与源上的共享访问签名一起使用。

   azcopy copy 'https://SOURCE-STORAGE-ACCOUNT-NAME.blob.core.windows.net/CONTAINER?SAS-TOKEN' 'https://DESTINATION-STORAGE-ACCOUNT-NAME.blob.core.windows.net/CONTAINER' --recursive
   

   对于 Google Cloud Storage，请使用 Google Cloud 命令行界面中的 gcloud storage rsync。

   gcloud storage rsync --recursive gs://SOURCE-BUCKET gs://DESTINATION-BUCKET
   

   对于 MinIO，请从 MinIO 客户端使用 mc mirror 。

   mc mirror SOURCE-ALIAS/SOURCE-BUCKET DESTINATION-ALIAS/DESTINATION-BUCKET
   

   复制完成后，使用提供程序的标准列表工具验证目标上的对象计数和总大小。 在继续之前调查任何差异。

2. 启用维护模式。 若要防止在切换期间将新对象写入源端，请在 你的 GitHub Enterprise Server 实例 上启用维护模式。 这会导致该实例对终端用户短暂下线。 有关详细信息，请参阅“启用和排定维护模式”。

3. 执行最终增量同步。 启用维护模式后，再次从初始复制步骤运行相同的复制命令。 这会包含在初始复制开始后写入源端的任何对象。

   例如，对于 Amazon S3：

   aws s3 sync s3://SOURCE-BUCKET s3://DESTINATION-BUCKET
   

4. 更新存储配置。 更新 你的 GitHub Enterprise Server 实例 为指向新存储位置。 保留与以前相同的身份验证方法。

   1. 登录到 管理控制台。 有关详细信息，请参阅“访问管理控制台”。

   2. 在“设置”边栏中，单击“ 操作”。

   3. 在“构件和日志存储”下，更新用于标识存储位置的字段，例如存储桶名称、账户名称、区域、角色 ARN 或连接字符串。 请勿更改身份验证方法。

   4. 单击“ 测试存储设置 ”以验证新配置。

      警告

      如果测试失败，请不要保存设置。 在继续之前，请调查失败并重新测试。 保存无效的存储配置可能会导致服务中断。

   5. 单击“ 保存设置” 并等待服务完全重启。

   或者，您可以使用 ghe-actions-precheck 进行基于凭据的身份验证，从命令行更新配置。 有关详细信息，请参阅“命令行实用程序”。

5. 验证迁移。 配置更改后，确认 GitHub Actions 可以从新的存储位置读取数据。

   1. 禁用维护模式。 有关详细信息，请参阅“启用和排定维护模式”。

   2. 在 你的 GitHub Enterprise Server 实例 的 Web UI 中，打开一个在迁移前完成的最近工作流运行。 确认：

      • 工作流运行日志加载。
      • 构建产物下载成功。

   3. 触发新的���作流运行并确认：

      • 此次运行已成功完成。
      • 日志和运行过程中生成的任何产物均可见。

   如果这些验证中有任何一项失败，请保留源存储，并参阅下面的 回滚 部分。

6. 停用源存储。 仅在验证成功完成后再继续操作，并预留足够的时间，以确保新存储位置状态正常。 作为准则，在删除源存储之前，至少保留一个完整备份周期的只读状态。

   准备好删除源存储时，请按照提供程序的标准过程删除存储桶或容器。

回滚

如果验证失败，或者在切换后遇到问题，请将 你的 GitHub Enterprise Server 实例 重新指向源存储位置以执行回滚。 源存储是您已确认无误的副本。 在回滚过程中，不要将数据从目标端复制回源端，因为在切换失败期间写入目标端的数据可能不完整或不一致，而将这些数据写回源端可能会损坏你唯一完好的副本。

如果验证失败或遇到问题：

1. 立即启用维护模式。
2. 在 中 管理控制台，还原原始存储配置值，然后单击“ 测试存储设置”，然后单击“ 保存设置”。
3. 禁用维护模式，并使用原始存储重新运行验证步骤。

成功回滚后，调查失败原因，并规划新一轮迁移。

GitHub Packages 注意事项

可以将相同的迁��方法应用于 GitHub Packages 外部存储，但存在以下重要差异。 在迁移已启用的实例 GitHub Packages 上的存储之前，请完整阅读此部分。

• OpenID Connect 不适用于 GitHub Packages。 GitHub Packages 仅支持对外部存储使用基于凭据的身份验证。 本文中的身份验证方法约束仍适用：在迁移过程中保持身份验证方法不变。
• GitHub Packages 对时序不匹配更为敏感。 在迁移窗口中发布包时，系统会同时创建新的存储对象和数据库记录。 为防止出现不一致，请从最终增量同步开始到新配置成功验证完成为止，始终保持维护模式处于启用状态。
• 如果同一提供程序同时提供这两种产品，请同时更新这两种配置。 如果您已将 GitHub Actions 和 GitHub Packages 配置为使用相同的提供程序类型，并且您要同时迁移二者，请将切换安排在同一个维护窗口内，并在禁用维护模式之前更新这两项配置。
• 如需进行 GitHub Packages 存储的跨提供商迁移，请联系 GitHub Enterprise 支持。 此处不涵盖跨提供程序迁移。

有关配置 GitHub Packages 存储的详细信息，请参阅 企业 GitHub Packages 使用入门。