使用 GitHub Actions Importer 从 CircleCI 迁移

法律声明

关于使用 GitHub Actions Importer 从 CircleCI 迁移

以下说明将指导你配置环境，以使用 GitHub Actions Importer 将 CircleCI 流水线迁移到 GitHub Actions。

先决条件

• 一个 CircleCI 帐户或组织，其中包含你想要转换为 GitHub Actions 工作流的项目和流水线。

• 访问权限，以便为你的帐户或组织创建 CircleCI 个人 API 令牌。

• 一个可以运行基于 Linux 的容器并可以安装必要工具的环境。

  • 已安装并运行 Docker。
  • 已安装 GitHub CLI。

  注意：GitHub Actions Importer 容器和 CLI 不需要安装在与 CI 平台相同的服务器上。

限制

使用 GitHub Actions Importer 从 CircleCI 迁移到 GitHub Actions 时存在一些限制

• 不支持不同工作流的作业之间的自动缓存。
• 仅在使用组织帐户时才支持 audit 命令。但是，dry-run 和 migrate 命令可与组织或用户帐户一起使用。

手动任务

某些 CircleCI 构造必须手动迁移。这些包括

• 上下文
• 项目级环境变量
• 未知作业属性
• 未知 orb

安装 GitHub Actions Importer CLI 扩展

1. 安装 GitHub Actions Importer CLI 扩展

   Bash

   gh extension install github/gh-actions-importer
   

2. 验证扩展是否已安装

   $ gh actions-importer -h
   Options:
     -?, -h, --help  Show help and usage information
   
   Commands:
     update     Update to the latest version of GitHub Actions Importer.
     version    Display the version of GitHub Actions Importer.
     configure  Start an interactive prompt to configure credentials used to authenticate with your CI server(s).
     audit      Plan your CI/CD migration by analyzing your current CI/CD footprint.
     forecast   Forecast GitHub Actions usage from historical pipeline utilization.
     dry-run    Convert a pipeline to a GitHub Actions workflow and output its yaml file.
     migrate    Convert a pipeline to a GitHub Actions workflow and open a pull request with the changes.
   

配置凭证

当使用 CircleCI 和 GitHub 时，configure CLI 命令用于设置 GitHub Actions Importer 所需的凭证和选项。

1. 创建 GitHub 个人访问令牌（经典）。有关详细信息，请参阅“管理个人访问令牌”。

   令牌必须具有workflow范围。

   创建令牌后，复制令牌并将其保存在安全位置以供以后使用。

2. 创建 CircleCI 个人 API 令牌。有关详细信息，请参阅 CircleCI 文档中的管理 API 令牌。

   创建令牌后，复制令牌并将其保存在安全位置以供以后使用。

3. 在终端中，运行 GitHub Actions Importer configure CLI 命令

   gh actions-importer configure
   

   configure命令将提示你提供以下信息

   • 对于“要配置哪些 CI 提供商？”，使用箭头键选择CircleCI，按Space选择它，然后按Enter。
   • 对于“GitHub 的个人访问令牌”，输入之前创建的个人访问令牌（经典）的值，然后按Enter。
   • 对于“GitHub 实例的基本 URL”，按Enter接受默认值（https://github.com）。
   • 对于“CircleCI 的个人访问令牌”，输入之前创建的 CircleCI 个人 API 令牌的值，然后按Enter。
   • 对于“CircleCI 实例的基本 URL”，按Enter接受默认值（https://circleci.com）。
   • 对于“CircleCI 组织名称”，输入 CircleCI 组织的名称，然后按Enter。

   configure命令的示例如下所示

   $ gh actions-importer configure
   ✔ Which CI providers are you configuring?: CircleCI
   Enter the following values (leave empty to omit):
   ✔ Personal access token for GitHub: ***************
   ✔ Base url of the GitHub instance: https://github.com
   ✔ Personal access token for CircleCI: ********************
   ✔ Base url of the CircleCI instance: https://circleci.com
   ✔ CircleCI organization name: mycircleciorganization
   Environment variables successfully updated.
   

4. 在你的终端中，运行 GitHub Actions Importer update CLI 命令以连接到 GitHub Packages Container 注册表，并确保容器镜像已更新到最新版本

   gh actions-importer update
   

   命令的输出应类似于以下内容

   Updating ghcr.io/actions-importer/cli:latest...
   ghcr.io/actions-importer/cli:latest up-to-date
   

对 CircleCI 执行审计

你可以使用 audit 命令来获得 CircleCI 组织中所有项目的概览。

audit 命令执行以下步骤

1. 获取 CircleCI 组织中定义的所有项目。
2. 将每个管道转换为等效的 GitHub Actions 工作流。
3. 生成一份报告，总结使用 GitHub Actions Importer 可以完成多全面、多复杂的迁移。

运行审计命令

要对 CircleCI 组织执行审计，请在你的终端中运行以下命令

gh actions-importer audit circle-ci --output-dir tmp/audit

检查审计结果

指定输出目录中的文件包含审计结果。请参阅 audit_summary.md 文件以获取审计结果摘要。

审计摘要包含以下部分。

管道

"管道" 部分包含有关 GitHub Actions Importer 完成的转换率的高级统计信息。

以下是可能出现在"管道"部分中的一些关键术语

• 成功的管道有 100% 的管道结构和各个项目自动转换为等效的 GitHub Actions。
• 部分成功的管道已转换所有管道结构，但是，有些各个项目未自动转换为等效的 GitHub Actions。
• 不受支持的管道是 GitHub Actions Importer 不支持的定义类型。
• 失败的管道在转换时遇到致命错误。这可能出于以下三个原因之一
  • 管道配置错误，在 Bamboo 中无效。
  • GitHub Actions Importer 在转换时遇到内部错误。
  • 网络响应不成功，导致管道不可访问，这通常是由于凭据无效。

构建步骤

“构建步骤”部分概述了所有管道中使用的各个构建步骤，以及 GitHub Actions Importer 自动转换了多少个构建步骤。

下面列出了一些可能出现在“构建步骤”部分中的关键术语

• 已知构建步骤是已自动转换为等效操作的步骤。
• 未知构建步骤是未自动转换为等效操作的步骤。
• 不受支持的构建步骤是以下任一步骤
  • GitHub Actions 从根本上不支持。
  • 配置方式与 GitHub Actions 不兼容。
• 操作是已转换工作流中使用的操作列表。这对于以下情况非常重要
  • 如果您使用 GitHub Enterprise Server，则需要收集要同步到您的实例的操作列表。
  • 定义已使用的组织级别允许操作列表。此操作列表是您的安全或合规团队可能需要查看的全面操作列表。

手动任务

“手动任务”部分概述了 GitHub Actions Importer 无法自动完成的任务，您必须手动完成这些任务。

下面列出了一些可能出现在“手动任务”部分中的关键术语

• 机密是已转换管道中使用的存储库或组织级别机密。必须在 GitHub Actions 中手动创建这些机密，才能使这些管道正常运行。有关更多信息，请参阅“在 GitHub Actions 中使用机密”。
• 自托管运行器是指已转换管道中引用的运行器标签，该运行器不是 GitHub 托管的运行器。您需要手动定义这些运行器，才能使这些管道正常运行。

文件

审计报告的最后一部分提供了在审计期间写入磁盘的所有文件的清单。

每个管道文件都包含审计中包含的各种文件，包括

• 在 GitHub 中定义的原始管道。
• 用于转换管道的任何网络响应。
• 已转换的工作流文件。
• 可用于对失败的管道转换进行故障排除的堆栈跟踪。

此外，workflow_usage.csv 文件包含每个成功转换的管道所使用的所有操作、秘密和运行程序的逗号分隔列表。这对于确定哪些工作流使用哪些操作、秘密或运行程序很有用，并且对于执行安全审查很有用。

预测潜在的 GitHub 操作使用情况

你可以使用 forecast 命令通过计算 CircleCI 中已完成管道运行中的指标来预测潜在的 GitHub 操作使用情况。

运行预测命令

要预测潜在的 GitHub 操作使用情况，请在终端中运行以下命令。默认情况下，GitHub 操作导入器在预测报告中包含前七天。

gh actions-importer forecast circle-ci --output-dir tmp/forecast_reports

检查预测报告

指定输出目录中的 forecast_report.md 文件包含预测结果。

下面列出了一些可能出现在预测报告中的关键词

• 作业计数是已完成作业的总数。

• 管道计数是使用的唯一管道的数量。

• 执行时间描述了运行程序在作业上花费的时间。此指标可用于帮助规划 GitHub 托管运行程序的成本。

  此指标与你预期在 GitHub 操作中花费的金额相关。这将根据用于这些分钟的硬件而有所不同。你可以使用 GitHub 操作定价计算器 来估算成本。

• 队列时间指标描述了作业等待运行程序可用以执行它所花费的时间。

• 并发作业指标描述了在任何给定时间运行的作业数量。此指标可用于定义应配置的运行程序数量。

此外，这些指标针对 CircleCI 中的每个运行程序队列进行定义。如果存在托管或自托管运行程序的混合，或高规格或低规格机器，这将特别有用，以便你可以看到特定于不同类型运行程序的指标。

对 CircleCI 管道执行空运行迁移

你可以使用 dry-run 命令将 CircleCI 管道转换为等效的 GitHub 操作工作流。空运行会在指定目录中创建输出文件，但不会打开拉取请求来迁移管道。

要对将 CircleCI 项目迁移到 GitHub Actions 进行试运行，请在终端中运行以下命令，将 my-circle-ci-project 替换为 CircleCI 项目的名称。

gh actions-importer dry-run circle-ci --output-dir tmp/dry-run --circle-ci-project my-circle-ci-project

您可以在指定的输出目录中查看试运行和转换后的工作流文件的日志。

如果 GitHub Actions Importer 无法自动转换某些内容，例如未知的构建步骤或部分成功的管道，您可能需要创建自定义转换器以进一步自定义转换过程。有关更多信息，请参阅“使用自定义转换器扩展 GitHub Actions Importer”。

执行 CircleCI 管道的生产迁移

您可以使用 migrate 命令转换 CircleCI 管道，并使用等效的 GitHub Actions 工作流打开一个拉取请求。

运行迁移命令

要将 CircleCI 管道迁移到 GitHub Actions，请在终端中运行以下命令，将 target-url 值替换为 GitHub 存储库的 URL，将 my-circle-ci-project 替换为 CircleCI 项目的名称。

gh actions-importer migrate circle-ci --target-url https://github.com/octo-org/octo-repo --output-dir tmp/migrate --circle-ci-project my-circle-ci-project

该命令的输出包括将转换后的工作流添加到存储库的拉取请求的 URL。成功输出的示例类似于以下内容

$ gh actions-importer migrate circle-ci --target-url https://github.com/octo-org/octo-repo --output-dir tmp/migrate --circle-ci-project my-circle-ci-project
[2022-08-20 22:08:20] Logs: 'tmp/migrate/log/actions-importer-20220916-014033.log'
[2022-08-20 22:08:20] Pull request: 'https://github.com/octo-org/octo-repo/pull/1'

检查拉取请求

成功运行 migrate 命令的输出包含一个链接，该链接指向将转换后的工作流添加到存储库的新拉取请求。

拉取请求的一些重要元素包括

• 在拉取请求说明中，有一个名为手动步骤的部分，其中列出了在完成将管道迁移到 GitHub Actions 之前必须手动完成的步骤。例如，本部分可能会告诉您创建在工作流中使用的任何秘密。
• 转换后的工作流文件。在拉取请求中选择已更改的文件选项卡，以查看将添加到 GitHub 存储库的工作流文件。

当您完成检查拉取请求后，您可以将其合并以将工作流添加到 GitHub 存储库。

参考

本部分包含有关在使用 GitHub Actions Importer 从 CircleCI 迁移时环境变量、可选参数和支持的语法的参考信息。

使用环境变量

GitHub Actions Importer 使用环境变量进行身份验证配置。在使用 configure 命令遵循配置流程时设置这些变量。有关更多信息，请参阅“配置凭据”部分。

GitHub Actions Importer 使用以下环境变量连接到你的 CircleCI 实例

• GITHUB_ACCESS_TOKEN：用于创建包含已转换工作流的拉取请求的个人访问令牌（经典版）（需要 repo 和 workflow 范围）。
• GITHUB_INSTANCE_URL：目标 GitHub 实例的 URL（例如，https://github.com）。
• CIRCLE_CI_ACCESS_TOKEN：用于使用你的 CircleCI 实例进行身份验证的 CircleCI 个人 API 令牌。
• CIRCLE_CI_INSTANCE_URL：CircleCI 实例的 URL（例如，https://circleci.com）。如果未设置该变量，则将 https://circleci.com 用作默认值。
• CIRCLE_CI_ORGANIZATION：你的 CircleCI 实例的组织名称。
• CIRCLE_CI_PROVIDER：存储管道源文件的所在位置（例如，github）。目前，仅支持 GitHub。
• CIRCLE_CI_SOURCE_GITHUB_ACCESS_TOKEN（可选）：用于使用你的源 GitHub 实例进行身份验证的个人访问令牌（经典版）（需要 repo 范围）。如果未提供，则会使用 GITHUB_ACCESS_TOKEN 的值。
• CIRCLE_CI_SOURCE_GITHUB_INSTANCE_URL（可选）：源 GitHub 实例的 URL。如果未提供，则会使用 GITHUB_INSTANCE_URL 的值。

这些环境变量可以在 GitHub Actions Importer 运行时加载的 .env.local 文件中指定。

可选参数

你可以将可选参数与 GitHub Actions Importer 子命令一起使用，以自定义你的迁移。

--source-file-path

你可以将 --source-file-path 参数与 forecast、dry-run 或 migrate 子命令一起使用。

默认情况下，GitHub Actions Importer 从源代码管理中获取管道内容。--source-file-path 参数告诉 GitHub Actions Importer 使用指定的源文件路径。

例如

gh actions-importer dry-run circle-ci --output-dir ./output/ --source-file-path ./path/to/.circleci/config.yml

如果你想在运行 forecast 子命令时提供多个源文件，则可以在文件路径值中使用模式匹配。例如，gh forecast --source-file-path ./tmp/previous_forecast/jobs/*.json 会向 GitHub Actions Importer 提供与 ./tmp/previous_forecast/jobs/*.json 文件路径匹配的任何源文件。

--config-file-path

你可以将 --config-file-path 参数与 audit、dry-run 和 migrate 子命令一起使用。

默认情况下，GitHub Actions Importer 从源代码管理中获取管道内容。--config-file-path 参数告诉 GitHub Actions Importer 使用指定的源文件。

--config-file-path 参数还可以用于指定已转换的复合操作应迁移到的存储库。

审计示例

在此示例中，GitHub Actions Importer 使用指定的 YAML 配置文件执行审计。

gh actions-importer audit circle-ci --output-dir ./output/ --config-file-path ./path/to/circle-ci/config.yml

要使用配置文件审计 CircleCI 实例，配置文件必须采用以下格式，并且每个 repository_slug 必须唯一

source_files:
  - repository_slug: circle-org-name/circle-project-name
    path: path/to/.circleci/config.yml
  - repository_slug: circle-org-name/some-other-circle-project-name
    path: path/to/.circleci/config.yml

空运行示例

在此示例中，GitHub Actions Importer 使用指定的 YAML 配置文件作为源文件执行空运行。

通过将配置文件中的 repository_slug 与 --circle-ci-organization 和 --circle-ci-project 选项的值进行匹配来选择管道。然后使用 path 来提取指定的源文件。

gh actions-importer dry-run circle-ci --circle-ci-project circle-org-name/circle-project-name --output-dir ./output/ --config-file-path ./path/to/circle-ci/config.yml

指定已转换复合操作的存储库

GitHub Actions Importer 使用提供给 --config-file-path 参数的 YAML 文件来确定已转换复合操作迁移到的存储库。

首先，您应该在没有 --config-file-path 参数的情况下运行审计

gh actions-importer audit circle-ci --output-dir ./output/

此命令的输出将包含一个名为 config.yml 的文件，其中包含由 GitHub Actions Importer 转换的所有复合操作的列表。例如，config.yml 文件可能包含以下内容

composite_actions:
  - name: my-composite-action.yml
    target_url: https://github.com/octo-org/octo-repo
    ref: main

您可以使用此文件指定应将可重用工作流或复合操作添加到哪个存储库和 ref。然后，您可以使用 --config-file-path 参数向 GitHub Actions Importer 提供 config.yml 文件。例如，您可以在运行 migrate 命令时使用此文件，为配置文件中定义的每个唯一存储库打开一个拉取请求

gh actions-importer migrate circle-ci --circle-ci-project my-project-name --output-dir output/ --config-file-path config.yml --target-url https://github.com/my-org/my-repo

--include-from

您可以将 --include-from 参数与 audit 子命令一起使用。

--include-from 参数指定一个文件，其中包含一个以行分隔的存储库列表，以将其包含在 CircleCI 组织的审计中。文件中未包含的任何存储库都将从审计中排除。

例如

gh actions-importer audit circle-ci --output-dir ./output/ --include-from repositories.txt

为此参数提供的文件必须是以行分隔的存储库列表，例如

repository_one
repository_two
repository_three

CircleCI 管道的受支持语法

下表显示了 GitHub Actions Importer 当前能够转换的属性类型。

CircleCI 管道	GitHub Actions	状态
cron 触发器	on.schedule	支持
环境	env jobs.<job_id>.env jobs.<job_id>.steps.env	支持
执行器	runs-on	支持
作业	作业	支持
作业	jobs.<job_id> jobs.<job_id>.name	支持
矩阵	jobs.<job_id>.strategy jobs.<job_id>.strategy.matrix	支持
参数	env workflow-dispatch.inputs	支持
步骤	jobs.<job_id>.steps	支持
when, unless	jobs.<job_id>.if	支持
触发器	on	支持
执行器	容器 服务	部分支持
orbs	操作	部分支持
执行器	自托管运行器	不支持
设置	不适用	不支持
版本	不适用	不支持

有关支持的 CircleCI 概念和 orb 映射的更多信息，请参阅 github/gh-actions-importer 存储库。

环境变量映射

GitHub Actions Importer 使用下表中的映射将默认 CircleCI 环境变量转换为 GitHub Actions 中最接近的等效项。

CircleCI	GitHub Actions
CI	$CI
CIRCLE_BRANCH	${{ github.ref }}
CIRCLE_JOB	${{ github.job }}
CIRCLE_PR_NUMBER	${{ github.event.number }}
CIRCLE_PR_REPONAME	${{ github.repository }}
CIRCLE_PROJECT_REPONAME	${{ github.repository }}
CIRCLE_SHA1	${{ github.sha }}
CIRCLE_TAG	${{ github.ref }}
CIRCLE_USERNAME	${{ github.actor }}
CIRCLE_WORKFLOW_ID	${{ github.run_number }}
CIRCLE_WORKING_DIRECTORY	${{ github.workspace }}
<< pipeline.id >>	${{ github.workflow }}
<< pipeline.number >>	${{ github.run_number }}
<< pipeline.project.git_url >>	$GITHUB_SERVER_URL/$GITHUB_REPOSITORY
<< pipeline.project.type >>	github
<< pipeline.git.tag >>	${{ github.ref }}
<< pipeline.git.branch >>	${{ github.ref }}
<< pipeline.git.revision >>	${{ github.event.pull_request.head.sha }}
<< pipeline.git.base_revision >>	${{ github.event.pull_request.base.sha }}

法律声明

部分内容已根据 MIT 许可证从 https://github.com/github/gh-actions-importer/ 改编

MIT License

Copyright (c) 2022 GitHub

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.