使用自定义转换器扩展 GitHub Actions 导入工具

关于自定义转换器

GitHub Actions Importer 提供了通过创建自定义转换器来扩展其内置映射的功能。自定义转换器可用于完成以下操作：

转换 GitHub Actions Importer 不自动转换的项，或修改项的转换方式。有关详细信息，请参阅“为项创建自定义转换器”。
将对运行器的引用转换为使用不同的运行器标签。有关详细信息，请参阅“为运行器创建自定义转换器”。
将现有管道中的环境变量值转换为 GitHub Actions 工作流。有关详细信息，请参阅“为环境变量创建自定义转换器”。

在 GitHub Actions Importer 中使用自定义转换器

自定义转换器包含的映射逻辑可以让 GitHub Actions Importer 用于转换插件、任务、运行器标签或环境变量，从而使用 GitHub Actions。自定义转换器是用构建在 Ruby 基础上的特定于域的语言 (DSL) 编写的，并在文件扩展名为 .rb 的文件中定义。

可以使用 --custom-transformers CLI 选项指定要用于 audit、dry-run 和 migrate 命令的自定义转换器文件。

例如，如果在名为 transformers.rb 的文件中定义了自定义转换器，可以使用以下命令将它们用于 GitHub Actions Importer：

gh actions-importer ... --custom-transformers transformers.rb

或者，可以使用 glob 模式语法指定多个自定义转换器文件。例如，如果多个自定义转换器文件位于名为 transformers 的目录中，你可以使用以下命令将它们全部提供给 GitHub Actions Importer：

gh actions-importer ... --custom-transformers transformers/*.rb

注意：使用自定义转换器时，自定义转换器文件必须位于运行 gh actions-importer 命令的同一目录或子目录中。

为项创建自定义转换器

可以创建自定义转换器，供 GitHub Actions Importer 在将现有生成步骤或触发器转换为 GitHub Actions 中的等效项时使用。在以下情况下，这特别有用：

GitHub Actions Importer 不自动转换项。
你想要更改 GitHub Actions Importer 转换项的方式。
你的现有管道使用自定义或专有扩展，例如 Jenkins 中的共享库，你需要定义这些步骤在 GitHub Actions 中应如何发挥作用。

GitHub Actions Importer 使用通过在 Ruby 基础上构建的 DSL 定义的自定义转换器。若要为生成步骤和触发器创建自定义转换器，需要满足以下条件：

每个自定义转换器文件必须至少包含一个 transform 方法。
每个 transform 方法都必须返回一个 Hash、Hash 的数组或 nil。这个返回的值将对应于 YAML 中定义的操作。有关操作的详细信息，请参阅“了解 GitHub Actions”。

用于生成步骤的示例自定义转换器

以下示例转换使用“buildJavaScriptApp”标识符运行各种 npm 命令的生成步骤：

Ruby

transform "buildJavaScriptApp" do |item|
  command = ["build", "package", "deploy"].map do |script|
    "npm run #{script}"
  end

  {
    name: "build javascript app",
    run: command.join("\n")
  }
end

transform "buildJavaScriptApp" do |item|
  command = ["build", "package", "deploy"].map do |script|
    "npm run #{script}"
  end

  {
    name: "build javascript app",
    run: command.join("\n")
  }
end

上面的示例生成了以下 GitHub Actions 工作流步骤。它由具有 buildJavaScriptApp 标识符的转换后的生成步骤组成：

- name: build javascript app
  run: |
    npm run build
    npm run package
    npm run deploy

transform 方法在参数中使用源 CI/CD 实例中的生成步骤的标识符。在此示例中，标识符为 buildJavaScriptLibrary。还可以使用逗号分隔的值将多个标识符传递给 transform 方法。例如 transform "buildJavaScriptApp", "buildTypeScriptApp" { |item| ... }。

注意：item 的数据结构将有所不同，具体取决于 CI/CD 平台和要转换的项的类型。

为运行器创建自定义转换器

可以自定义源 CI/CD 实例中的运行器与其等效 GitHub Actions 运行器之间的映射。

GitHub Actions Importer 使用通过在 Ruby 基础上构建的 DSL 定义的自定义转换器。若要为运行器创建自定义转换器，需要满足以下条件：

自定义转换器文件必须至少包含一个 runner 方法。
runner 方法接受两个参数。第一个参数是源 CI/CD 实例的运行器标签，第二个参数是相应的 GitHub Actions 运行器标签。有关 GitHub Actions 运行器的详细信息，请参阅“使用 GitHub 托管的运行器”。

运行器的示例自定义转换器

以下示例演示了一个 runner 方法，该方法在生成的工作流中将一个运行器标签转换为一个 GitHub Actions 运行器标签。

Ruby

runner "linux", "ubuntu-latest"

runner "linux", "ubuntu-latest"

你还可以使用 runner 方法在生成的工作流中将一个运行器标签转换为多个 GitHub Actions 运行器标签。

Ruby

runner "big-agent", ["self-hosted", "xl", "linux"]

runner "big-agent", ["self-hosted", "xl", "linux"]

GitHub Actions Importer 尝试尽可能映射运行器标签。如果它无法执行此操作，ubuntu-latest 运行器标签将用作默认值。可以将特殊关键字与 runner 方法一起使用来控制此默认值。例如，以下自定义转换器指示 GitHub Actions Importer 将 macos-latest 用作默认运行器，而不是 ubuntu-latest。

Ruby

runner :default, "macos-latest"

runner :default, "macos-latest"

为环境变量创建自定义转换器

可以将源 CI/CD 管道中的环境变量之间的映射自定义为它们在 GitHub Actions 中的值。

GitHub Actions Importer 使用通过在 Ruby 基础上构建的 DSL 定义的自定义转换器。若要为环境变量创建自定义转换器，需要满足以下条件：

自定义转换器文件必须至少包含一个 env 方法。
env 方法接受两个参数。第一个参数是原始管道中环境变量的名称，第二个参数是 GitHub Actions 的环境变量的更新值。有关 GitHub Actions 环境变量的详细信息，请参阅“在变量中存储信息”。

环境变量的示例自定义转换器

可通过多种方式设置自定义转换器来映射环境变量。

以下示例在转换管道时，将名为 OCTO 的任何现有环境变量的值设置为 CAT。
Ruby
```
env "OCTO", "CAT"
```
```
env "OCTO", "CAT"
```
还可以删除特定环境变量的所有实例，以便它们不会转换为 GitHub Actions 工作流。以下示例删除名为 MONA_LISA 的所有环境变量。
Ruby
```
env "MONA_LISA", nil
```
```
env "MONA_LISA", nil
```
你还可以将现有环境变量映射到机密。例如，以下 env 方法将名为 MONALISA 的环境变量映射到名为 OCTOCAT 的机密。
Ruby
```
env "MONALISA", secret("OCTOCAT")
```
```
env "MONALISA", secret("OCTOCAT")
```
这会设置对已转换工作流中名为 OCTOCAT 的机密的引用。若要使机密正常工作，需要在 GitHub 存储库中创建机密。有关详细信息，请参阅“在 GitHub Actions 中使用机密”。
还可以使用正则表达式一次更新多个环境变量的值。例如，以下自定义转换器从转换后的工作流中删除所有环境变量：
Ruby
```
env /.*/, nil
```
```
env /.*/, nil
```
以下示例使用正则表达式匹配组，以将环境变量值转换为动态生成的机密。
Ruby
```
env /^(.+)_SSH_KEY/, secret("%s_SSH_KEY)
```
```
env /^(.+)_SSH_KEY/, secret("%s_SSH_KEY)
```
注意：使用正则表达式时，env 方法的定义顺序很重要。与环境变量名称匹配的第一个 env 转换器优先于后续 env 方法。应首先定义最具体的环境变量转换器。

法律通告

部分内容改编自 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.

使用自定义转换器扩展 GitHub Actions 导入工具

本文内容