importer-labs/gitlab/5-custom-transformers.md

Using custom transformers to customize Valet's behavior

In this lab you will build upon the dry-run command to override Valet's default behavior and customize the converted workflow using "custom transformers". Custom transformers can be used to:

1. Convert items that are not automatically converted.
2. Convert items that were automatically converted using different actions.
3. Convert environment variable values differently.
4. Convert references to runners to use a different runner name in Actions.

Prerequisites

1. Followed the steps here to set up your GitHub Codespaces environment and start your GitLab server.
2. Completed the configure lab.
3. Completed the dry-run lab.

Perform a dry-run

You will be performing a dry-run command to inspect the workflow that is converted by default. Run the following command within the codespace terminal:

gh valet dry-run gitlab --output-dir tmp --namespace valet --project terraform-example

The converted workflow that is generated by the above command can be seen below:

Converted workflow 👇

name: valet/custom-transformer
on:
  push:
  workflow_dispatch:
concurrency:
  group: "${{ github.ref }}"
  cancel-in-progress: true
jobs:
  plan:
    runs-on: ubuntu-latest
    timeout-minutes: 60
    env:
      PLAN: plan.cache
      PLAN_JSON: plan.json
    steps:
    - uses: actions/checkout@v2
      with:
        fetch-depth: 20
        lfs: true
    - run: terraform plan -out=$PLAN
    - run: terraform show --json $PLAN | convert_report > $PLAN_JSON
#     # 'artifacts.terraform' was not transformed because there is no suitable equivalent in GitHub Actions

Note: You can refer to the previous lab to learn about the fundamentals of the dry-run command.

Custom transformers for an unknown step

The converted workflow above contains an artifacts.terraform step that was not automatically converted. Answer the following questions before writing a custom transformer:

1. What is the "identifier" of the step to customize?

   • artifacts.terraform

2. What is the desired Actions syntax to use instead?

   • After some research, you have determined that the following GitHub Action will provide similar functionality:

     - uses: actions/upload-artifact@v3
       with:
         path: VALUE_FROM_GITLAB
     

Now you can begin to write the custom transformer. Custom transformers use a DSL built on top of Ruby and should be defined in a file with the .rb file extension. You can create this file by running the following command in your codespace terminal:

touch transformers.rb && code transformers.rb

Next, you will define a transform method for the artifacts.terraform identifier by adding the following code to transformers.rb:

transform "artifacts.terraform" do |item|
  {
    uses: "actions/upload-artifact@v3",
    with: {
      path: item
    }
  }
end

This method can use any valid ruby syntax and should return a Hash that represents the YAML that should be generated for a given step. Valet will use this method to convert a step with the provided identifier and will use the item parameter for the original values configured in GitLab.

Now you can perform another dry-run command and use the --custom-transformers CLI option to provide this custom transformer. Run the following command within your codespace terminal:

gh valet dry-run gitlab --output-dir tmp --namespace valet --project terraform-example --custom-transformers transformers.rb

The converted workflow that is generated by the above command will now use the custom logic for the artifacts.terraform step.

- #     # 'artifacts.terraform' was not transformed because there is no suitable equivalent in GitHub Actions
+ uses: actions/upload-artifact@v2
+ with:
+   path: "$PLAN_JSON"

Note: If you were unsure what the data structure of item was, you could use the following code in the custom transformer to print item to the console:

transform "artifacts.terraform" do |item|
  puts item
end

Custom transformers for environment variables

You can also use custom transformers to edit the values of environment variables in converted workflows. In this example, you will update the PLAN_JSON environment variable to be custom_plan.json instead of plan.json.

To do this, add the following code to the transformers.rb file.

env "PLAN_JSON", "custom_plan.json"

In this example, the first parameter to the env method is the environment variable name and the second is the updated value.

Now you can perform another dry-run command with the --custom-transformers CLI option. When you open the converted workflow the PLAN_JSON environment variable will be set to custom_plan.json:

 env:
   PLAN: plan.cache
-  PLAN_JSON: plan.json
+  PLAN_JSON: custom_plan.json

At this point, the file contents of transformers.rb should match this:

Custom transformers 👇

  env "PLAN_JSON", "custom_plan.json"

  transform "artifacts.terraform" do |item|
    {
      uses: "actions/upload-artifact@v2",
      with: {
        path: item
      }
    }
  end

That's it! Congratulations, you have overridden Valet's default behavior by customizing the conversion of:

• Unknown steps
• Environment variables

Next lab

Perform a production migration of a GitLab pipeline