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

关于自定义转换器

GitHub Actions 导入器能够通过创建自定义转换器来扩展其内置映射。自定义转换器可用于

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

将自定义转换器与 GitHub Actions 导入器一起使用

自定义转换器包含 GitHub Actions 导入器可用于将您的插件、任务、运行器标签或环境变量转换为与 GitHub Actions 协同工作的映射逻辑。自定义转换器使用构建在 Ruby 之上的特定领域语言 (DSL) 编写，并在扩展名为 .rb 的文件中定义。

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

例如，如果自定义转换器在名为 transformers.rb 的文件中定义，则可以使用以下命令将它们与 GitHub Actions 导入器一起使用

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

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

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

注意

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

为项目创建自定义转换器

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

GitHub Actions 导入器无法自动转换某个项目。
您想更改 GitHub Actions 导入器转换项目的方式。
您现有的管道使用自定义或专有扩展（例如 Jenkins 中的共享库），并且您需要定义这些步骤在 GitHub Actions 中应如何运行。

GitHub Actions 导入器使用基于 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 导入器使用基于 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 导入器会尽力映射运行器标签。在无法执行此操作的情况下，将使用 ubuntu-latest 运行器标签作为默认值。您可以使用 runner 方法中的特殊关键字来控制此默认值。例如，以下自定义转换器指示 GitHub Actions 导入器使用 macos-latest 作为默认运行器，而不是 ubuntu-latest。

Ruby

runner :default, "macos-latest"

runner :default, "macos-latest"

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

您可以自定义源 CI/CD 管道中的环境变量与其在 GitHub Actions 中的值之间的映射。

GitHub Actions 导入器使用基于 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 方法。您应首先定义最具体的环境变量转换器。

法律声明

部分内容已从 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.

本文内容