> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Demo Custom Transformer Runner variables
> How to use a custom transformer to map CI/CD runner labels and centralize environment variable mappings when migrating pipelines to GitHub Actions
In this lesson you will learn how to use a custom transformer to translate source CI/CD runner labels into equivalent GitHub Actions runners and to centralize environment variable mappings. This is useful when migrating pipelines (for example, from Jenkins) that reference self-hosted agents or custom labels so they run on GitHub-hosted runners like `ubuntu-latest`.
What the transformer provides
* A `runner` helper to map a source runner label to one or more GitHub Actions runner labels.
* `env` helpers to centralize environment variables or map them to repository secrets.
Common runner mapping examples
| Source label | GitHub Actions label(s) | Notes |
| ------------ | -------------------------------- | ----------------------------------------------- |
| `linux` | `ubuntu-latest` | Single-label mapping (string) |
| `big-agent` | `["self-hosted", "xl", "linux"]` | Multiple labels (array) for self-hosted runners |
Example mappings (Ruby syntax):
```ruby theme={null}
runner "linux", "ubuntu-latest"
runner "big-agent", ["self-hosted", "xl", "linux"]
```
* First parameter: source CI/CD runner label (string).
* Second parameter: GitHub Actions label(s), either a string or an array of strings.
Dry-run the importer to preview generated workflows
Run a one-time dry-run of the importer to produce the converted workflow files (trimmed output shown):
```bash theme={null}
gh actions-importer dry-run jenkins \
--source-url http://139.84.149.83:8080/job/ci-pipeline-poll-scm/ \
--output-dir tmp/dry-run \
--custom-transformers ss-pipeline-transformer.rb
# Example output (trimmed)
[2025-05-22 13:00:39] Logs: 'tmp/dry-run/log/valet-20250522-130039.log'
[2025-05-22 13:00:40] Output file(s):
tmp/dry-run/ci-pipeline-poll-scm/.github/workflows/ci-pipeline-poll-scm.yml
```
Original converted workflow (example)
Some jobs in the converted workflow may still reference self-hosted runner labels and agent-specific labels, for example:
```yaml theme={null}
on:
push:
branches:
- main
schedule:
- cron: '00 00 * * *'
env:
MONGO_URI: mongodb+srv://supercluster.d83jj.mongodb.net/superData
MONGO_USERNAME: superuser
MONGO_PASSWORD: "${{ secrets.mongo_db_password }}"
jobs:
Installing_Dependencies:
name: Installing Dependencies
runs-on:
- self-hosted
- us-west-1-ubuntu-22
container:
image: node:24
```
Update the transformer to map runners and envs
To replace source labels with GitHub-hosted runners and to centralize environment variables, add mappings at the top of your transformer file (for example `ss-pipeline-transformer.rb`).
Example transformer mappings:
```ruby theme={null}
# Map environment variables (set literal or map to secrets)
env "MONGO_USERNAME", "superuser"
env "MONGO_PASSWORD", secret("mongo_db_password")
env "MONGO_DB_CREDS", nil
# Map Jenkins/JB agent label to GitHub Actions runner
runner "us-west-1-ubuntu-22", "ubuntu-latest"
```
When writing the mapping lines, ensure correct Ruby syntax (commas between parameters). For instance: `runner "us-west-1-ubuntu-22", "ubuntu-latest"`.
Re-run the dry-run with your custom transformer
After saving the transformer, run the dry-run again to regenerate the workflow with the mapped runners and centralized env entries:
```bash theme={null}
gh actions-importer dry-run jenkins \
--source-url http://139.84.149.83:8080/job/ci-pipeline-poll-scm/ \
--output-dir tmp/dry-run \
--custom-transformers ss-pipeline-transformer.rb
```
Resulting workflow (example)
The importer will now emit workflows using the mapped runners and the transformed environment variable entries:
```yaml theme={null}
name: ci-pipeline-poll-scm
on:
push:
branches:
- main
schedule:
- cron: 00 00 * * *
env:
MONGO_URI: mongodb+srv://supercluster.d83jj.mongodb.net/superData
MONGO_USERNAME: superuser
MONGO_PASSWORD: "${{ secrets.mongo_db_password }}"
jobs:
Installing_Dependencies:
name: Installing Dependencies
runs-on:
- ubuntu-latest
container:
image: node:24
```
Next steps and references
* Review all runner mappings in your transformer to ensure coverage for every agent label used in source pipelines.
* Use `env` to centralize common variables and `secret("...")` to map values to repository secrets.
Links and references
* [GitHub Actions Documentation](https://docs.github.com/actions)
* [GitHub CLI — gh actions-importer (project)](https://github.com/actions/importer)