Extending GitHub Actions Importer with custom transformers

Legal notice

About custom transformers

GitHub Actions Importer offers the ability to extend its built-in mapping by creating custom transformers. Custom transformers can be used to:

• Convert items that GitHub Actions Importer does not automatically convert, or modify how items are converted. For more information, see Creating custom transformers for items.
• Convert references to runners to use different runner labels. For more information, see Creating custom transformers for runners.
• Convert environment variable values from your existing pipelines to GitHub Actions workflows. For more information, see Creating custom transformers for environment variables.

Using custom transformers with GitHub Actions Importer

A custom transformer contains mapping logic that GitHub Actions Importer can use to transform your plugins, tasks, runner labels, or environment variables to work with GitHub Actions. Custom transformers are written with a domain-specific language (DSL) built on top of Ruby, and are defined within a file with the .rb file extension.

You can use the --custom-transformers CLI option to specify which custom transformer files to use with the audit, dry-run, and migrate commands.

For example, if custom transformers are defined in a file named transformers.rb, you can use the following command to use them with GitHub Actions Importer:

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

Alternatively, you can use the glob pattern syntax to specify multiple custom transformer files. For example, if multiple custom transformer files are within a directory named transformers, you can provide them all to GitHub Actions Importer with the following command:

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

Creating custom transformers for items

You can create custom transformers that GitHub Actions Importer will use when converting existing build steps or triggers to their equivalent in GitHub Actions. This is especially useful when:

• GitHub Actions Importer doesn't automatically convert an item.
• You want to change how an item is converted by GitHub Actions Importer.
• Your existing pipelines use custom or proprietary extensions, such as shared libraries in Jenkins, and you need to define how these steps should function in GitHub Actions.

GitHub Actions Importer uses custom transformers that are defined using a DSL built on top of Ruby. In order to create custom transformers for build steps and triggers:

• Each custom transformer file must contain at least one transform method.
• Each transform method must return a Hash, an array of Hash's, or nil. This returned value will correspond to an action defined in YAML. For more information about actions, see Understanding GitHub Actions.

Example custom transformer for a build step

The following example converts a build step that uses the "buildJavaScriptApp" identifier to run various npm commands:

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

The above example results in the following GitHub Actions workflow step. It is comprised of converted build steps that had a buildJavaScriptApp identifier:

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

The transform method uses the identifier of the build step from your source CI/CD instance in an argument. In this example, the identifier is buildJavaScriptLibrary. You can also use comma-separated values to pass multiple identifiers to the transform method. For example, transform "buildJavaScriptApp", "buildTypeScriptApp" { |item| ... }.

Creating custom transformers for runners

You can customize the mapping between runners in your source CI/CD instance and their equivalent GitHub Actions runners.

GitHub Actions Importer uses custom transformers that are defined using a DSL built on top of Ruby. To create custom transformers for runners:

• The custom transformer file must have at least one runner method.
• The runner method accepts two parameters. The first parameter is the source CI/CD instance's runner label, and the second parameter is the corresponding GitHub Actions runner label. For more information on GitHub Actions runners, see