关于使用 GitHub Actions Importer 从 Jenkins 迁移
以下说明将指导您配置环境以使用 GitHub Actions Importer 将 Jenkins 管道迁移到 GitHub Actions。
先决条件
-
一个 Jenkins 帐户或组织,其中包含您要转换为 GitHub Actions 工作流程的管道和作业。
-
访问权限,以便为您的帐户或组织创建 Jenkins 个人 API 令牌。
-
一个可以运行基于 Linux 的容器的环境,并且可以安装必要的工具。
- Docker 已安装并正在运行。
- GitHub CLI 已安装。
注意:GitHub Actions Importer 容器和 CLI 不需要安装在与您的 CI 平台相同的服务器上。
限制
使用 GitHub Actions Importer 从 Jenkins 迁移到 GitHub Actions 时,存在一些限制。例如,您必须手动迁移以下结构
- 必备构建工具
- 脚本化管道
- 密钥
- 自托管运行器
- 未知插件
有关手动迁移的更多信息,请参阅“从 Jenkins 迁移到 GitHub Actions”。
安装 GitHub Actions Importer CLI 扩展
-
安装 GitHub Actions Importer CLI 扩展
Bash gh extension install github/gh-actions-importer
gh extension install github/gh-actions-importer
-
验证扩展是否已安装
$ 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 命令用于在使用 Jenkins 和 GitHub 时为 GitHub Actions Importer 设置所需的凭据和选项。
-
创建一个 GitHub 个人访问令牌(经典)。有关更多信息,请参阅“管理您的个人访问令牌”。
您的令牌必须具有
workflow
范围。创建令牌后,将其复制并保存在安全位置以备后用。
-
创建一个 Jenkins API 令牌。有关更多信息,请参阅 Jenkins 文档中的 验证脚本化客户端。
创建令牌后,将其复制并保存在安全位置以备后用。
-
在您的终端中,运行 GitHub Actions Importer
configure
CLI 命令gh actions-importer configure
configure
命令将提示您输入以下信息- 对于“您要配置哪些 CI 提供商?”,使用箭头键选择
Jenkins
,按 Space 选择它,然后按 Enter。 - 对于“GitHub 的个人访问令牌”,输入您之前创建的个人访问令牌(经典)的值,然后按 Enter。
- 对于“GitHub 实例的基准 URL”,按 Enter 接受默认值(
https://github.com
)。 - 对于“Jenkins 的个人访问令牌”,输入您之前创建的 Jenkins 个人 API 令牌的值,然后按 Enter。
- 对于“Jenkins 用户的用户名”,输入您的 Jenkins 用户名并按 Enter。
- 对于“Jenkins 实例的基准 URL”,输入您的 Jenkins 实例的 URL,然后按 Enter。
下面显示了
configure
命令的示例$ gh actions-importer configure ✔ Which CI providers are you configuring?: Jenkins 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 Jenkins: *************** ✔ Username of Jenkins user: admin ✔ Base url of the Jenkins instance: https://127.0.0.1 Environment variables successfully updated.
- 对于“您要配置哪些 CI 提供商?”,使用箭头键选择
-
在您的终端中,运行 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
执行 Jenkins 审计
您可以使用 audit
命令来获取 Jenkins 服务器中所有管道的概览。
audit
命令执行以下步骤
- 获取 Jenkins 服务器中定义的所有项目。
- 将每个管道转换为等效的 GitHub Actions 工作流。
- 生成一份报告,总结使用 GitHub Actions Importer 可以实现的迁移的完整性和复杂程度。
运行审计命令
要执行 Jenkins 服务器的审计,请在您的终端中运行以下命令
gh actions-importer audit jenkins --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
文件包含每个成功转换的管道使用的所有操作、秘密和运行器的逗号分隔列表。这对于确定哪些工作流使用哪些操作、秘密或运行器非常有用,并且对于执行安全审查也很有用。
预测潜在的构建运行器使用情况
您可以使用 forecast
命令通过计算 Jenkins 服务器中已完成的管道运行的指标来预测潜在的 GitHub Actions 使用情况。
运行预测命令的先决条件
为了对 Jenkins 实例运行 forecast
命令,您必须在 Jenkins 服务器上安装 paginated-builds
插件。此插件允许 GitHub Actions Importer 有效地检索具有大量构建的作业的历史构建数据。由于 Jenkins 没有提供检索分页构建数据的方法,因此使用此插件可以防止从 Jenkins 服务器获取大量历史数据时可能发生的超时。paginated-builds
插件是开源的,并公开了一个 REST API 端点,用于分页获取构建数据,而不是一次性获取所有数据。
安装 paginated-builds
插件
- 在您的 Jenkins 实例上,导航到
https://<您的 Jenkins 实例>/pluginManager/available
。 - 搜索
paginated-builds
插件。 - 选中左侧的复选框并选择 **不重启安装**。
运行预测命令
要对潜在的 GitHub Actions 进行预测,请在您的终端中运行以下命令。默认情况下,GitHub Actions Importer 会在预测报告中包含前七天。
gh actions-importer forecast jenkins --output-dir tmp/forecast
检查预测报告
指定输出目录中的 forecast_report.md
文件包含预测结果。
以下是预测报告中可能出现的一些关键术语
- **作业数量** 是已完成作业的总数。
- **流水线数量** 是使用的唯一流水线的数量。
- **执行时间** 描述了运行器在作业上花费的时间。此指标可用于帮助规划 GitHub 托管运行器的成本。
- 此指标与您预计在 GitHub Actions 中花费的金额相关。这将根据用于这些分钟的硬件而有所不同。您可以使用 GitHub Actions 定价计算器 来估算成本。
- **排队时间** 指标描述了作业等待运行器可用以执行它所花费的时间。
- **并发作业** 指标描述了在任何给定时间运行的作业数量。此指标可用于定义您应该配置的运行器数量。
此外,这些指标还针对 Jenkins 中的每个运行器队列进行了定义。如果存在托管或自托管运行器,或高规格或低规格机器的混合,这将特别有用,因此您可以查看特定于不同类型运行器的指标。
执行 Jenkins 流水线的试运行迁移
您可以使用 dry-run
命令将 Jenkins 流水线转换为等效的 GitHub Actions 工作流程。
运行试运行命令
您可以使用 dry-run
命令将 Jenkins 流水线转换为等效的 GitHub Actions 工作流程。试运行会在指定目录中创建输出文件,但不会打开拉取请求来迁移流水线。
要对将 Jenkins 流水线迁移到 GitHub Actions 进行试运行,请在您的终端中运行以下命令,将 my-jenkins-project
替换为您的 Jenkins 作业的 URL。
gh actions-importer dry-run jenkins --source-url my-jenkins-project --output-dir tmp/dry-run
检查转换后的工作流程
您可以在指定的输出目录中查看干运行的日志和转换后的工作流程文件。
如果 GitHub Actions Importer 无法自动转换某些内容,例如未知的构建步骤或部分成功的管道,您可能需要创建自定义转换器以进一步定制转换过程。有关更多信息,请参阅“使用自定义转换器扩展 GitHub Actions Importer”。
执行 Jenkins 管道的生产迁移
您可以使用 migrate
命令转换 Jenkins 管道,并使用等效的 GitHub Actions 工作流程打开拉取请求。
运行 migrate 命令
要将 Jenkins 管道迁移到 GitHub Actions,请在您的终端中运行以下命令,将 target-url
值替换为您的 GitHub 存储库的 URL,并将 my-jenkins-project
替换为您的 Jenkins 作业的 URL。
gh actions-importer migrate jenkins --target-url https://github.com/:owner/:repo --output-dir tmp/migrate --source-url my-jenkins-project
该命令的输出包括将转换后的工作流程添加到您的存储库的拉取请求的 URL。成功输出的示例类似于以下内容
$ gh actions-importer migrate jenkins --target-url https://github.com/octo-org/octo-repo --output-dir tmp/migrate --source-url https://127.0.0.1:8080/job/monas_dev_work/job/monas_freestyle
[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 从 Jenkins 迁移时有关环境变量、可选参数和支持的语法的参考信息。
使用环境变量
GitHub Actions Importer 使用环境变量进行其身份验证配置。这些变量在使用 configure
命令遵循配置过程时设置。有关更多信息,请参阅“配置凭据”部分。
GitHub Actions Importer 使用以下环境变量连接到您的 Jenkins 实例
-
GITHUB_ACCESS_TOKEN
:用于使用转换后的工作流程创建拉取请求的个人访问令牌(经典)(需要repo
和workflow
范围)。 -
GITHUB_INSTANCE_URL
: 目标 GitHub 实例的 URL(例如,https://github.com
)。 -
JENKINS_ACCESS_TOKEN
: 用于查看 Jenkins 资源的 Jenkins API 令牌。注意:此令牌需要访问您要迁移或审核的所有作业。在文件夹或作业未从其父级继承访问控制列表的情况下,您必须授予显式权限或完全管理员权限。
-
JENKINS_USERNAME
: 创建 Jenkins API 令牌的用户帐户的用户名。 -
JENKINS_INSTANCE_URL
: Jenkins 实例的 URL。 -
JENKINSFILE_ACCESS_TOKEN
(可选)用于检索存储在构建存储库中的Jenkinsfile
内容的 API 令牌。这需要repo
范围。如果未提供此令牌,则将使用GITHUB_ACCESS_TOKEN
。
这些环境变量可以在 .env.local
文件中指定,该文件在运行 GitHub Actions Importer 时加载。
使用可选参数
您可以使用 GitHub Actions Importer 子命令的可选参数来自定义迁移。
--source-file-path
您可以将 --source-file-path
参数与 forecast
、dry-run
或 migration
子命令一起使用。
默认情况下,GitHub Actions Importer 从源代码管理中获取管道内容。--source-file-path
参数告诉 GitHub Actions Importer 使用指定的源文件路径。您可以将此选项用于 Jenkinsfile 和多分支管道。
如果您想在运行 forecast
子命令时提供多个源文件,可以在文件路径值中使用模式匹配。例如,gh forecast --source-file-path ./tmp/previous_forecast/jobs/*.json
为 GitHub Actions Importer 提供与 ./tmp/previous_forecast/jobs/*.json
文件路径匹配的任何源文件。
Jenkinsfile 管道示例
在此示例中,GitHub Actions Importer 使用指定的 Jenkinsfile 作为源文件来执行干运行。
gh actions-importer dry-run jenkins --output-dir path/to/output/ --source-file-path path/to/Jenkinsfile --source-url :url_to_jenkins_job
--config-file-path
您可以将 --config-file-path
参数与 audit
、dry-run
和 migrate
子命令一起使用。
默认情况下,GitHub Actions Importer 从源代码管理中获取管道内容。--config-file-path
参数告诉 GitHub Actions Importer 使用指定的源文件。
当您将 --config-file-path
选项与 dry-run
或 migrate
子命令一起使用时,GitHub Actions Importer 会将存储库标识符与 --source-url
选项表示的作业匹配以选择管道。它使用 config-file-path
来拉取指定的源文件。
审核示例
在此示例中,GitHub Actions Importer 使用指定的 YAML 配置文件来执行审核。
gh actions-importer audit jenkins --output-dir path/to/output/ --config-file-path path/to/jenkins/config.yml
要使用配置文件审核 Jenkins 实例,配置文件必须采用以下格式,并且每个 repository_slug
值必须唯一
source_files:
- repository_slug: pipeline-name
path: path/to/Jenkinsfile
- repository_slug: multi-branch-pipeline-name
branches:
- branch: main
path: path/to/Jenkinsfile
- branch: node
path: path/to/Jenkinsfile
Jenkins 管道的支持语法
下表显示了 GitHub Actions 导入器当前能够转换的属性类型。有关 Jenkins 管道语法如何与 GitHub Actions 对齐的更多详细信息,请参阅“从 Jenkins 迁移到 GitHub Actions”。
有关支持的 Jenkins 插件的信息,请参阅 github/gh-actions-importer
存储库。
自由式管道的支持语法
Jenkins | GitHub Actions | 状态 |
---|---|---|
docker 模板 | jobs.<job_id>.container | 支持 |
构建 | 作业 | 部分支持 |
构建环境 | env | 部分支持 |
构建触发器 | on | 部分支持 |
常规 | 运行器 | 部分支持 |
Jenkinsfile 管道的支持语法
Jenkins | GitHub Actions | 状态 |
---|---|---|
docker | jobs.<job_id>.container | 支持 |
阶段 | jobs.<job_id> | 支持 |
代理 | 运行器 | 部分支持 |
环境 | env | 部分支持 |
阶段 | 作业 | 部分支持 |
步骤 | jobs.<job_id>.steps | 部分支持 |
触发器 | on | 部分支持 |
when | jobs.<job_id>.if | 部分支持 |
输入 | 输入 | 不支持 |
矩阵 | jobs.<job_id>.strategy.matrix | 不支持 |
选项 | jobs.<job_id>.strategy | 不支持 |
参数 | 输入 | 不支持 |
环境变量语法
GitHub Actions 导入器使用下表中的映射将默认的 Jenkins 环境变量转换为 GitHub Actions 中最接近的等效项。
Jenkins | GitHub Actions |
---|---|
${BUILD_ID} | ${{ github.run_id }} |
${BUILD_NUMBER} | ${{ github.run_id }} |
${BUILD_TAG} | ${{ github.workflow }}-${{ github.run_id }} |
${BUILD_URL} | ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} |
${JENKINS_URL} | ${{ github.server_url }} |
${JOB_NAME} | ${{ github.workflow }} |
${WORKSPACE} | ${{ github.workspace }} |
法律声明
部分内容已从 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.