diff --git a/Readme.md b/Readme.md index e6cf8bf..7935203 100644 --- a/Readme.md +++ b/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. diff --git a/lib/models/arguments.rb b/lib/models/arguments.rb index 12aa66d..f67c7b5 100644 --- a/lib/models/arguments.rb +++ b/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| diff --git a/spec/models/arguments_spec.rb b/spec/models/arguments_spec.rb index e72deca..28ff873 100644 --- a/spec/models/arguments_spec.rb +++ b/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