Merge branch 'main' into cm/wf-add

Readme.md

@@ -16,7 +16,7 @@ Complete the following steps:
 
 1. Create a new repository using this repository as the template by clicking [here](https://github.com/actions/importer-issue-ops/generate).
 2. Create the following labels in this new repository, if they are not already present: `jenkins`, `azure-devops`, `circle-ci`, `gitlab`, `travis-ci`, and `actions-importer-running`.
-3. Add the repository secrets described below that are relevant to the CI/CD providers being migrated:
+3. Add the repository secrets described below that are relevant to the CI/CD providers being migrated.
 
 ### All CI/CD providers
 
@@ -95,6 +95,30 @@ Optionally, the following environment variables can be set:
 
 Once configured, pipelines can be migrated to GitHub Actions by opening an issue with the relevant issue template and following the instructions.
 
+### Custom transformers
+
+Custom transformers can be used to customize the behavior of Actions Importer to meet your specific use-case. Custom transformers can be used to:
+
+- Convert items that are not automatically converted.
+- Convert items that were automatically converted using different actions.
+- Convert environment variable values differently.
+- Convert references to runners to use a different runner name in Actions.
+
+Custom transformers must be defined in a file with the `.rb` file extension within a directory named `transformers` in your IssueOps repository. Alternatively, you can provide specific custom transformers to be used by appending the `--custom-transformers` option in the issue comment used to trigger Actions Importer. For example:
+
+```
+/migrate ... --custom-transformers my-transformers.rb
+```
+
+You can learn more about authoring custom transformers by completing the self-guided learning exercises below:
+
+- Custom transformers for Azure DevOps pipelines [exercise](https://github.com/actions/importer-labs/blob/main/azure_devops/5-custom-transformers.md)
+- Custom transformers for CircleCI pipelines [exercise](https://github.com/actions/importer-labs/blob/main/circle_ci/5-custom-transformers.md)
+- Custom transformers for GitLab pipelines [exercise](https://github.com/actions/importer-labs/blob/main/gitlab/5-custom-transformers.md)
+- Custom transformers for Jenkins pipelines [exercise](https://github.com/actions/importer-labs/blob/main/jenkins/5-custom-transformers.md)
+- Custom transformers for Travis CI pipelines [exercise](https://github.com/actions/importer-labs/blob/main/travis/5-custom-transformers.md)
+
+
 ## Privacy statement
 
 GitHub Actions Importer will collect anonymous telemetry when running to help us improve the tool. This can be disabled by adding the `--no-telemetry` flag to any command provided to the GitHub Actions Importer CLI.

lib/models/arguments.rb

@@ -7,16 +7,23 @@ class Arguments
 
   def initialize(provider, command, issue_content)
     @args = argument_class(provider, command, issue_content)
+    @custom_transformers = custom_transformers(command)
   end
 
   def argument_class(provider, command, issue_content)
     provider.module.const_get(command.classify).new(issue_content, command)
   end
 
+  def custom_transformers(command)
+    command.options&.dig("custom-transformers")&.split(" ") || Dir.glob("transformers/**/*.rb")
+  end
+
   def to_output
     arguments = @args.to_a
     return if arguments.blank?
 
+    arguments.concat(["--custom-transformers", *@custom_transformers]) if @custom_transformers.length.positive?
+
     set_output(
       "args",
       arguments.map do |a|

spec/models/arguments_spec.rb

@@ -13,6 +13,7 @@ RSpec.describe Arguments do
       before do
         expect(provider).to receive(:module).and_return(::Jenkins).at_least(:once)
         expect(command).to receive(:classify).and_return("Audit").at_least(:once)
+        expect(command).to receive(:options).and_return({})
       end
 
       it { is_expected.to be_a(::Jenkins::Audit) }
@@ -31,9 +32,12 @@ RSpec.describe Arguments do
   describe "#to_output" do
     subject { arguments.to_output }
 
+    let(:options) { {} }
+
     before do
       expect(provider).to receive(:module).and_return(::AzureDevops).at_least(:once)
       expect(command).to receive(:classify).and_return("Audit").at_least(:once)
+      expect(command).to receive(:options).and_return(options)
       expect_any_instance_of(::AzureDevops::Audit).to receive(:to_a).and_return(output)
     end
 
@@ -63,5 +67,29 @@ RSpec.describe Arguments do
         subject
       end
     end
+
+    context "when there is a custom transformers option" do
+      let(:output) { ["--option", "value"] }
+      let(:options) { { "custom-transformers" => "transformers/**/*.rb" } }
+
+      it "writes an output variable" do
+        expect(arguments).to receive(:set_output).with("args", "--option value --custom-transformers transformers/**/*.rb")
+        subject
+      end
+    end
+
+    context "when there are custom transformers in the repository" do
+      let(:output) { ["--option", "value"] }
+      let(:files) { ["transformers/jenkins/transformers.rb", "transformers/all.rb"] }
+
+      before do
+        expect(Dir).to receive(:glob).with("transformers/**/*.rb").and_return(files)
+      end
+
+      it "writes an output variable" do
+        expect(arguments).to receive(:set_output).with("args", "--option value --custom-transformers transformers/jenkins/transformers.rb transformers/all.rb")
+        subject
+      end
+    end
   end
 end