使用自定义转换器扩展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 实例中的 runner 与其对应的 GitHub Actions runner 之间的映射关系。

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导入工具

在本文中