使用 GitHub Actions Importer 从 Travis CI 迁移

了解如何使用 GitHub Actions Importer 自动迁移您的 Travis CI 管道到 GitHub Actions。

本文内容

法律声明

关于使用 GitHub Actions Importer 从 Travis CI 迁移

以下说明将指导您配置环境，以便使用 GitHub Actions Importer 将 Travis CI 管道迁移到 GitHub Actions。

先决条件

  • 一个 Travis CI 账户或组织，其中包含您想转换为 GitHub Actions 工作流程的管道和作业。
  • 访问权限，以便为您的帐户或组织创建 Travis CI API 访问令牌。
  • 一个可以运行基于 Linux 的容器，并可以安装必要工具的环境。

    注意

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

限制

使用 GitHub Actions Importer 从 Travis CI 管道迁移到 GitHub Actions 时，存在一些限制。

手动任务

某些 Travis CI 结构必须手动迁移。这些包括：

  • 密钥
  • 未知作业属性

有关手动迁移的更多信息，请参见“从 Travis CI 迁移到 GitHub Actions”。

Travis CI 项目语言

GitHub Actions Importer 通过向转换后的工作流程添加一组预配置的构建工具和默认构建脚本，来转换 Travis CI 项目语言。如果未显式声明任何语言，GitHub Actions Importer 将假定项目语言为 Ruby。

有关 GitHub Actions Importer 支持的项目语言列表，请参见“支持的项目语言”。

安装 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.

配置凭据

configure CLI 命令用于在使用 Travis CI 和 GitHub 时设置 GitHub Actions Importer 的必需凭据和选项。

  1. 创建一个 GitHub 个人访问令牌（经典版）。有关更多信息，请参见“管理您的个人访问令牌”。

    您的令牌必须具有 workflow 作用域。

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

  2. 创建 Travis CI API 访问令牌。有关更多信息，请参见 Travis CI 文档中的获取您的 Travis CI API 令牌。

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

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

    gh actions-importer configure

    configure 命令将提示您输入以下信息：

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

    configure 命令输出示例如下所示。

    $ gh actions-importer configure
✔ Which CI providers are you configuring?: Travis CI
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 Travis CI: ***************
✔ Base url of the Travis CI instance: https://www.travis-ci.cn
✔ Travis CI organization name: actions-importer-labs
Environment variables successfully updated.

  4. 在您的终端中，运行 GitHub Actions Importer update CLI 命令以连接到 GitHub Packages Container registry 并确保容器映像已更新到最新版本。

    gh actions-importer update

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

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

执行 Travis CI 审计

您可以使用 audit 命令获取 Travis CI 服务器中所有管道的概览。

audit 命令执行以下步骤：

  1. 获取在 Travis CI 服务器中定义的所有项目。
  2. 将每个管道转换为其等效的 GitHub Actions 工作流程。
  3. 生成一份报告，总结使用 GitHub Actions Importer 可以实现迁移的完整性和复杂程度。

运行审计命令

要在您的终端中执行 Travis CI 服务器的审计，请运行以下命令：

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

检查审计结果

指定输出目录中的文件包含审计结果。有关审计结果的摘要，请参见 audit_summary.md 文件。

审计摘要包含以下部分：

管道

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

以下是“管道”部分中可能出现的一些关键词：

  • 成功的管道已将 100% 的管道结构和单个项目自动转换为其 GitHub Actions 等效项。
  • 部分成功的管道已转换所有管道结构，但是，某些单个项目未自动转换为其 GitHub Actions 等效项。
  • 不支持的管道是 GitHub Actions Importer 不支持的定义类型。
  • 失败的管道在转换时遇到致命错误。这可能是由于以下三个原因之一：
    • 管道最初配置错误且无效。
    • 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 文件包含所有操作、密钥和运行器的逗号分隔列表，这些操作、密钥和运行器由每个成功转换的管道使用。这对于确定哪些工作流程使用哪些操作、密钥或运行器非常有用，并且对于执行安全审查非常有用。

预测潜在的构建运行器使用情况

您可以使用 forecast 命令通过计算 Travis CI 服务器中已完成的管道运行的指标来预测潜在的 GitHub Actions 使用情况。

运行预测命令

要在您的终端中执行潜在 GitHub Actions 使用情况的预测，请运行以下命令。默认情况下，GitHub Actions Importer 在预测报告中包含前七天。

gh actions-importer forecast travis-ci --output-dir tmp/forecast

检查预测报告

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

以下是预测报告中可能出现的一些关键词：

  • 作业数是已完成作业的总数。
  • 管道数是使用的唯一管道的数量。
  • 执行时间描述运行器在一个作业上花费的时间。此指标可用于帮助规划 GitHub 托管运行器的成本。
    • 此指标与您在 GitHub Actions 中预计的支出金额相关。这将根据这些分钟使用的硬件而有所不同。您可以使用GitHub Actions 价格计算器来估算成本。
  • 排队时间指标描述作业等待运行器可用以执行它所花费的时间。
  • 并发作业指标描述了任何给定时间运行的作业数量。此指标可用于定义应配置的运行程序数量。

此外，这些指标针对 Travis CI 中的每个运行程序队列进行定义。如果混合使用托管或自托管运行程序，或高规格或低规格的机器，这尤其有用，因此您可以查看特定于不同类型运行程序的指标。

执行 Travis CI 管道的试运行迁移

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

要执行将 Travis CI 管道迁移到 GitHub Actions 的试运行，请在您的终端中运行以下命令，将my-travis-ci-repository替换为您 Travis CI 仓库的名称。

gh actions-importer dry-run travis-ci --travis-ci-repository my-travis-ci-repository --output-dir tmp/dry-run

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

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

执行 Travis CI 管道的生产迁移

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

运行 migrate 命令

要将 Travis CI 管道迁移到 GitHub Actions，请在您的终端中运行以下命令，将target-url值替换为您 GitHub 仓库的 URL，并将my-travis-ci-repository替换为您 Travis CI 仓库的名称。

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

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

$ gh actions-importer migrate travis-ci --target-url https://github.com/octo-org/octo-repo --output-dir tmp/migrate --travis-ci-repository my-travis-ci-repository
[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 从 Travis CI 迁移时的环境变量、可选参数和支持的语法方面的参考信息。

使用环境变量

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

GitHub Actions Importer 使用以下环境变量连接到您的 Travis CI 实例

  • GITHUB_ACCESS_TOKEN：用于使用转换后的工作流程创建拉取请求的个人访问令牌（经典）（需要workflow范围）。
  • GITHUB_INSTANCE_URL：目标 GitHub 实例的 URL（例如，https://github.com）。
  • TRAVIS_CI_ACCESS_TOKEN：用于查看 Travis CI 资源的 Travis CI API 访问令牌。
  • TRAVIS_CI_ORGANIZATION：您的 Travis CI 实例的组织名称。
  • TRAVIS_CI_INSTANCE_URL：Travis CI 实例的 URL。
  • TRAVIS_CI_SOURCE_GITHUB_ACCESS_TOKEN：（可选）用于向您的源 GitHub 实例进行身份验证的个人访问令牌。如果未提供，则将使用GITHUB_ACCESS_TOKEN。
  • TRAVIS_CI_SOURCE_GITHUB_INSTANCE_URL：（可选）源 GitHub 实例的 URL，例如https://github.com。如果未提供，则将使用GITHUB_INSTANCE_URL。

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

使用可选参数

您可以将可选参数与 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 travis-ci --output-dir ./path/to/output/ --travis-ci-repository my-travis-ci-repository --source-file-path ./path/to/.travis.yml

--allow-inactive-repositories

您可以使用此参数指定 GitHub Actions Importer 是否应在审核中包含非活动仓库。如果未设置此选项，则审核中不包含非活动仓库。

gh actions-importer dry-run travis-ci --output-dir ./path/to/output/ --travis-ci-repository my-travis-ci-repository --allow-inactive-repositories

--config-file-path

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

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

审核示例

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

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

要使用配置文件审核 Travis CI 实例，该文件必须采用以下格式，并且每个repository_slug值必须唯一

source_files:
  - repository_slug: travis-org-name/travis-repo-name
    path: path/to/.travis.yml
  - repository_slug: travis-org-name/some-other-travis-repo-name
    path: path/to/.travis.yml
试运行示例

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

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

gh actions-importer dry-run travis-ci --travis-ci-repository travis-org-name/travis-repo-name --output-dir ./output/ --config-file-path ./path/to/travis-ci/config.yml

支持的项目语言

GitHub Actions Importer 支持迁移以下语言的 Travis CI 项目。

  • android
  • bash
  • c
  • clojure
  • c++
  • crystal
  • c#
  • d
  • dart
  • elixir
  • erlang
  • generic
  • go
  • groovy
  • haskell
  • haxe
  • java
  • julia
  • matlab
  • minimal
  • nix
  • node_js
  • objective-c
  • perl
  • perl6
  • php
  • python
  • r
  • ruby
  • rust
  • scala
  • sh
  • shell
  • smalltalk
  • swift

支持的 Travis CI 管道语法

下表显示了 GitHub Actions Importer 目前能够转换的属性类型。有关 Travis CI 管道语法如何与 GitHub Actions 对齐的更多详细信息，请参见从 Travis CI 迁移到 GitHub Actions。

Travis CIGitHub Actions状态
branches
  • on.<push>.<branches>
支持
build_pull_requests
  • on.<pull_request>
支持
env
  • env
  • jobs.<job_id>.env
  • jobs.<job_id>.steps.env
支持
if
  • jobs.<job_id>.if
支持
job
  • jobs.<job_id>
  • jobs.<job_id>.name
支持
matrix
  • jobs.<job_id>.strategy
  • jobs.<job_id>.strategy.fail-fast
  • jobs.<job_id>.strategy.matrix
支持
os & dist
  • runners
支持
scripts
  • jobs.<job_id>.steps
支持
stages
  • jobs
支持
env
  • on
部分支持
branches
  • on.<push>.<tags>
  • on.<push>.paths
不支持
build_pull_requests
  • on.<pull_request>.<branches>
  • on.<pull_request>.<tags>
  • on.<pull_request>.paths
不支持
cron 触发器
  • on.schedule
  • on.workflow_run
不支持
env
  • jobs.<job_id>.timeout-minutes
  • on.<event_name>.types
不支持
job
  • jobs.<job_id>.container
不支持
os & dist
  • 自托管运行程序
不支持

有关支持的 Travis CI 结构的信息，请参见github/gh-actions-importer 仓库。

环境变量语法

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

Travis CIGitHub Actions
$CONTINUOUS_INTEGRATION$CI
$USER${{ github.actor }}
$HOME${{ github.workspace }}
$TRAVIS_BRANCH${{ github.ref }}
$TRAVIS_BUILD_DIR${{ github.workspace }}
$TRAVIS_BUILD_ID${{ github.run_number }}
$TRAVIS_BUILD_NUMBER${{ github.run_id }}
$TRAVIS_COMMIT${{ github.sha }}
$TRAVIS_EVENT_TYPE${{ github.event_name }}
$TRAVIS_PULL_REQUEST_BRANCH${{ github.base_ref }}
$TRAVIS_PULL_REQUEST${{ github.event.number }}
$TRAVIS_PULL_REQUEST_SHA${{ github.head.sha }}
$TRAVIS_PULL_REQUEST_SLUG${{ github.repository }}
$TRAVIS_TAG${{ github.ref }}
$TRAVIS_OS_NAME${{ runner.os }}
$TRAVIS_JOB_ID${{ github.job }}
$TRAVIS_REPO_SLUG${{ github.repository_owner/github.repository }}
$TRAVIS_BUILD_WEB_URL${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}

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

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.