Demo Custom Transformer sleep

In this lesson you’ll create a custom transformer that converts a Jenkins sleep step into an equivalent GitHub Actions step. Instead of leaving the sleep step commented out in the generated workflow, the transformer will produce a step like:

- name: Sleep for 5 seconds
  run: sleep 5s

This guide walks through inspecting the Jenkins pipeline JSON, writing a helper transformer to verify the structure, and implementing the final transformer in Ruby. It also shows how to run gh actions-importer with your custom transformer for dry-run and migrate.

Problem overview

When the importer doesn’t have a built-in transformer for an identifier like sleep, it reports:

“failed to locate transformer” for sleep
the step is left commented out in the generated workflow

Example of a generated workflow where sleep was previously commented out:

name: Second Stage
runs-on: ubuntu-latest
needs: First_Stage
steps:
  - name: checkout
    uses: actions/checkout@v4.1.0
  - name: echo message
    run: echo Starting the second stage...
# This item has no matching transformer
#  - sleep:
#      _key: time
#      value:
#        isLiteral: true
#        value: 20
  - name: Sleep for 5 seconds
    run: sleep 5s
  - name: echo message
    run: echo Second stage completed.

We need a transformer that reads the time argument from the Jenkins representation and dynamically generates the proper run: sleep <Ns> step.

How the Jenkins step appears in the importer JSON

The importer receives each pipeline step as a JSON item. For sleep, the JSON looks like:

{
  "name": "sleep",
  "arguments": [
    {
      "key": "time",
      "value": {
        "isLiteral": true,
        "value": 20
      }
    }
  ]
}

The numeric sleep value is available at arguments[0].value.value (for example, 5 or 20). Extract that value in your transformer and use it to build the GitHub Actions step.

Transformer basics

Transformers are Ruby .rb files that define one or more transform blocks (DSL entries).
Each transform block should return a Ruby Hash that maps to the GitHub Actions YAML for a step.
Provide transformer files to the CLI with --custom-transformers for audit, dry-run, or migrate.

Example CLI usage:

gh actions-importer dry-run jenkins \
  --source-url http://139.84.149.83:8080/job/folder-1/job/folder-2/job/pipeline-project-2 \
  --output-dir tmp/dry-run \
  --custom-transformers helper-transformer.rb

Use dry-run to validate your transformer output before running a full migration. This prevents creating PRs with incorrect workflows.

Step 1 — Helper transformer to inspect `sleep` items

Start by creating a small helper transformer that prints each sleep item so you can confirm the JSON structure and the path to the time value. Save as helper-transformer.rb:

# helper-transformer.rb
transform "sleep" do |item|
  puts "JSON for sleep identifier: #{item}"
end

Run the importer with:

gh actions-importer dry-run jenkins \
  --source-url http://139.84.149.83:8080/job/folder-1/job/folder-2/job/pipeline-project-2 \
  --output-dir tmp/dry-run \
  --custom-transformers helper-transformer.rb

You should see output like:

JSON for sleep identifier: {"name"=>"sleep", "arguments"=>[{"key"=>"time", "value"=>{"isLiteral"=>true, "value"=>5}}]}
JSON for sleep identifier: {"name"=>"sleep", "arguments"=>[{"key"=>"time", "value"=>{"isLiteral"=>true, "value"=>20}}]}

This confirms where the time value is located in each sleep item.

Step 2 — Final `sleep` transformer

Now implement the transformer that extracts the time value and returns a hash representing the corresponding GitHub Actions step. Save it as sleep-transformer.rb:

# sleep-transformer.rb
transform 'sleep' do |item|
  # Extract the sleep duration from the step's arguments
  sleep_time = item["arguments"][0]["value"]["value"]

  # Return a Hash representing the GitHub Actions step
  {
    "name" => "Sleep for #{sleep_time} seconds",
    "run"  => "sleep #{sleep_time}s"
  }
end

Notes:

Access the time via item["arguments"][0]["value"]["value"].
Return a Ruby Hash with string keys; the importer converts it into YAML for the workflow.

Run a dry-run using this transformer:

gh actions-importer dry-run jenkins \
  --source-url http://139.84.149.83:8080/job/folder-1/job/folder-2/job/pipeline-project-2 \
  --output-dir tmp/dry-run \
  --custom-transformers sleep-transformer.rb

If successful, the generated workflow will include transformed sleep steps.

Example generated YAML after transformation

name: folder-1/folder-2/pipeline-project-2
on:
  workflow_dispatch:
jobs:
  First_Stage:
    name: First Stage
    runs-on: ubuntu-latest
    steps:
      - name: checkout
        uses: actions/checkout@v4.1.0
      - name: echo message
        run: echo Starting the first stage...
      - name: Sleep for 5 seconds
        run: sleep 5s
      - name: echo message
        run: echo First stage completed.
  Second_Stage:
    name: Second Stage
    runs-on: ubuntu-latest
    needs: First_Stage
    steps:
      - name: checkout
        uses: actions/checkout@v4.1.0
      - name: echo message
        run: echo Starting the second stage...
      - name: Sleep for 20 seconds
        run: sleep 20s
      - name: echo message
        run: echo Second stage completed.

Migrating with the transformer

You can supply the transformer to the migrate command. Example:

gh actions-importer migrate jenkins \
  --target-url https://github.com/jenkins-demo-org/demo-repo \
  --output-dir tmp/migrate \
  --source-url http://139.84.149.83:8080/job/folder-1/job/folder-2/job/pipeline-project-2 \
  --custom-transformers sleep-transformer.rb

If the migration succeeds, the importer creates a pull request in the target repository (for example: https://github.com/jenkins-demo-org/demo-repo/pull/3) that contains the converted workflow including the dynamically generated sleep steps. You can review and merge that PR on GitHub.

A screenshot of a GitHub pull request page titled "Convert folder-1/folder-2/pipeline-project-2 to GitHub Actions." The page shows a comment saying the pipeline was migrated from Jenkins and the commit message / merge confirmation form.

Summary checklist

Task	Why it matters	Example / Command
Create transformer file	Transformers define how identifiers map to workflow YAML	`sleep-transformer.rb`
Inspect pipeline JSON	Ensures you extract the correct value path	Use `helper-transformer.rb` with `dry-run`
Use `--custom-transformers`	Provide custom logic to the importer	`--custom-transformers sleep-transformer.rb`
Test with `dry-run`	Validate output before making changes to a repo	`gh actions-importer dry-run jenkins --custom-transformers sleep-transformer.rb`
Migrate to create PR	Apply transformer during migration to produce a PR	`gh actions-importer migrate jenkins --custom-transformers sleep-transformer.rb`

Ensure you access literal values correctly (e.g., item["arguments"][0]["value"]["value"]). Returning an incorrect structure can cause the importer to leave the item untransformed.

Final example transformer (recap)

transform 'sleep' do |item|
  sleep_time = item["arguments"][0]["value"]["value"]

  {
    "name" => "Sleep for #{sleep_time} seconds",
    "run"  => "sleep #{sleep_time}s"
  }
end

With this pattern you can implement custom transformers for other Jenkins identifiers (for example: node, environment variables, or custom build steps) that the importer does not convert automatically.

Links and references

GitHub Actions importer docs
Jenkins Pipeline Syntax
gh CLI: gh actions-importer commands (use --help for details)

Migration Overview

Analyze Your Existing Jenkins Pipelines

Fundamentals of GitHub Actions

Manual Migration From Jenkins to GitHub Actions

Automate Migration From Jenkins to GitHub Actions

Introduction

Demo Custom Transformer sleep

Problem overview

How the Jenkins step appears in the importer JSON

Transformer basics

Step 1 — Helper transformer to inspect `sleep` items

Step 2 — Final `sleep` transformer

Example generated YAML after transformation

Migrating with the transformer

Summary checklist

Final example transformer (recap)

Links and references

Watch Video

​Problem overview

​How the Jenkins step appears in the importer JSON

​Transformer basics

​Step 1 — Helper transformer to inspect sleep items

​Step 2 — Final sleep transformer

​Example generated YAML after transformation

​Migrating with the transformer

​Summary checklist

​Final example transformer (recap)

​Links and references

Watch Video

Problem overview

How the Jenkins step appears in the importer JSON

Transformer basics

Step 1 — Helper transformer to inspect `sleep` items

Step 2 — Final `sleep` transformer

Example generated YAML after transformation

Migrating with the transformer

Summary checklist

Final example transformer (recap)

Links and references