What are Custom Transformers

Custom transformers let you tailor the GitHub Actions Importer’s behavior when converting CI/CD pipelines. They solve cases where the importer’s default conversion logic cannot accurately translate platform-specific constructs, custom steps, or organization-specific practices into GitHub Actions workflows. Why use custom transformers?

Handle non-standard items: Pipelines often include proprietary extensions—such as shared libraries in Jenkins, Azure DevOps templates, or GitLab custom jobs—that standard migration tools may not convert correctly. Custom transformers allow you to define precise mappings from these platform-specific constructs to GitHub Actions steps or jobs.
Address complex pipeline logic: Some pipelines contain intricate control flow, custom scripts, or non-trivial dependency wiring. Instead of leaving these items unconverted, a transformer lets you programmatically interpret and emit equivalent GitHub Actions YAML so the migrated workflow behaves as expected.
Adapt to organizational standards: Naming conventions, security constraints, and CI/CD best practices differ across teams. With transformers you can enforce consistent job names, environment variable policies, or secrets handling during migration.

A presentation slide titled "Needs for Custom Transformers" showing three colored boxes of challenges on the left and two numbered points on the right about converting custom/proprietary extensions (for example, shared Jenkins libraries) and mapping non-standard items to GitHub Actions workflows.

Practical scenarios where custom transformers help:

Converting non-standard Jenkins steps or plugins that the importer cannot parse.
Rewriting scripted pipeline logic (Groovy) to shell commands or composite actions.
Mapping platform-specific job labels or runner identifiers to GitHub Actions runners and labels.

A presentation slide titled "Needs for Custom Transformers" with three colored boxes on the left listing requirements and a large panel on the right. The right panel shows two numbered points: "Handle intricate logic, custom scripts, or dependencies" and "Ensure migrated workflows function correctly."

Summary table: When to add a custom transformer

Situation	What to do	Example
Importer leaves comments like “no matching transformer”	Implement a transformer for that step identifier	`sleep` step in Jenkinsfile
Complex scripted logic	Create transformer to emit a multi-step GitHub Actions job	Wrap script in `run` steps or create composite action
Organization conventions	Add transformer to rename jobs, enforce env vars, or inject security checks	Add standardized job `name` and `env` keys

A presentation slide titled "Needs for Custom Transformers" showing three colored boxes listing needs (handling non-standard items, addressing complex pipeline structures, adapting to unique organizational needs). On the right are two numbered points about supporting CI/CD practices, naming/security needs and tailoring workflows to organizational standards.

Example: Converting a Jenkins `sleep` Step

Below is a small end-to-end example that demonstrates identifying a Jenkins step the importer could not convert, writing a custom transformer, and running a dry run to see the converted GitHub Actions workflow. Jenkinsfile (Groovy)

pipeline {
    agent {
        label 'TeamARunner'
    }

    environment {
        DISABLE_AUTH = 'true'
        DB_ENGINE    = 'sqlite'
    }

    stages {
        stage('build') {
            steps {
                echo "Database engine is ${DB_ENGINE}"
                sleep 80
                echo "DISABLE_AUTH is ${DISABLE_AUTH}"
            }
        }
        stage('test') {
            steps{
                junit '**/target/*.xml'
            }
        }
    }
}

Generated GitHub Actions workflow (before custom transformer)

name: test_pipeline
on:
  push:
env:
  DISABLE_AUTH: 'true'
  DB_ENGINE: sqlite
jobs:
  build:
    runs-on:
      - self-hosted
      - TeamARunner
    steps:
    - name: checkout
      uses: actions/checkout@v2
    - name: echo message
      run: echo "Database engine is ${{ env.DB_ENGINE }}"
    # # This item has no matching transformer
    # - sleep:
    #   - key: time
    #     value:
    #       isLiteral: true
    #       value: 80
    - name: echo_message
      run: echo "DISABLE_AUTH is ${{ env.DISABLE_AUTH }}"
  test:
    runs-on:
      - self-hosted
      - TeamARunner
    needs: build
    steps:
    - name: checkout
      uses: actions/checkout@v2
    - name: Publish test results
      uses: EnricoMi/publish-unit-test-result-action@v1.7
      if: always()
      with:
        files: "**/target/*.xml"

You can see the importer left the sleep step commented out with a note that there was no matching transformer. The next steps are: identify the Jenkins step and decide the equivalent GitHub Actions syntax. Identify the step Recognize the Jenkins step identifier (sleep) and check its arguments in the importer-provided item structure.

A presentation slide titled "Custom Transformer" showing an orange rounded box labeled "Step identifier?" with an arrow pointing to a gray rounded box that reads "It's sleep (from the Jenkinsfile key-value)." The slide also has a small "© Copyright KodeKloud" notice in the bottom-left.

Decide target GitHub Actions syntax For a simple sleep step, a shell command is the appropriate GitHub Actions representation: GitHub Actions step (YAML)

- name: Sleep for 80 seconds
  run: sleep 80s
  shell: bash

Create the custom transformer Transformers are written in a domain-specific language built on Ruby and saved in a .rb file. A transformer matches the Jenkins step identifier, extracts arguments from the importer item, and returns a Ruby hash that serializes to the desired GitHub Actions step. Example transformer (transformers.rb)

transform "sleep" do |item|
  # Extract the sleep time value from the Jenkins step arguments
  wait_time = item["arguments"][0]["value"]["value"]

  # Return a hash representing the GitHub Actions step
  {
    "name" => "Sleep for #{wait_time} seconds",
    "run"  => "sleep #{wait_time}s",
    "shell"=> "bash"
  }
end

Ensure the transformer returns a valid Ruby hash (string or symbol keys are acceptable) that the importer can serialize to YAML. Use the actual item structure provided by the importer to access nested values correctly.

Run the importer with your custom transformers Save your transformer file (for example, transformers.rb) and run a dry run of the importer, passing the file with --custom-transformers. Inspect the output directory to verify the converted workflow. Example dry-run command

gh actions-importer dry-run jenkins \
  --url http://localhost:8080/job/test_pipeline \
  --output-dir tmp/dry-run \
  --custom-transformers transformers.rb

Expected change (diff-style)

- #  # This item has no matching transformer
- #  - sleep:
- #  -   - key: time
- #  -     value:
- #  -       isliteral: true
- #  -       value: 80
+ - name: Sleep for 80 seconds
+   run: sleep 80s
+   shell: bash

You can author multiple transformers—one per Jenkins identifier or other platform construct—to systematically convert non-standard items across your pipelines.

Test transformers in a dry run before applying them broadly. Mis-parsed item structures or incorrect Ruby hashes can produce invalid YAML or unwanted workflow behavior. Keep backups of original pipeline definitions.

​Example: Converting a Jenkins sleep Step

Watch Video

Example: Converting a Jenkins `sleep` Step