Docs

Transformer

Description

The "transformers" parameter can be used by any stage definition as a "source", "condition", or "target". A "transformers" object contains a list of transformers. Each kind of transformer rules applies a string manipulation like adding or removing characters.

source

Source returns information modified by a list of transformers.

condition

A condition receives information from the source then modifies that value using transformers before using it in the resource.

target

A target receives information from the source then modifies that value with the transformers rule before using the resource.

Parameters

NameDefaultDescription

addprefix

-

Add a prefix to the value

addsuffix

-

Add a suffix to the value

trimprefix

-

Remove a prefix from the value, if present

trimsuffix

-

Remove a suffix from the value, if present

replacers

-

A list of Replacer, applied as a single pass, more here

replacer

-

Replace a string with another one, more here

find

-

Return the first substring matching a regular expression, or an empty string when there is no match

findsubmatch

-

Search for a substring using a regular expression and return a capture group, more here

semverinc

-

Bump a semantic version, accepts a comma separated list of "major", "minor", "patch"

quote

false

Add quotes around the value

unquote

false

Remove quotes around the value

jsonmatch

-

Query a JSON value with a dasel selector, more here

Important

A single list entry may hold several of those keys, and they are then applied in the fixed order of the table above, not in the order they are written in the manifest.

To control the order, use one list entry per operation:

transformers:
  # Applied first
  - trimprefix: "v"
  # Applied second
  - addprefix: "release-"
Note
Transformer keys are lowercase. The camelCase spellings addPrefix, addSuffix, trimPrefix, trimSuffix, semverInc, findSubMatch, and captureIndex are deprecated: they still work but log a warning, and are ignored when the lowercase form is also present.

Transformers never receive an empty value: an empty input aborts the transformation with a validation error.

Replacer

A replacer rule modifies the information by replacing every occurrence of the "from" value by the "to" value. from and to are plain strings, not regular expressions.

NameRequiredDefaultDescription

from

✔

-

"from" value defines the string that will be replaced

to

✔

-

"to" value defines the string that we want to have

replacers accepts a list of those rules and applies them in a single pass, so a replacement never rewrites the output of an earlier one:

transformers:
  - replacers:
      - from: "alpha"
        to: "beta"
      # "beta" produced by the previous rule is left untouched
      - from: "beta"
        to: "gamma"

FindSubMatch

A findsubmatch rule captures the desired information by applying pattern as a regular expression and returning one of its capture groups.

NameRequiredDefaultDescription

pattern

✔

-

pattern value defines the regular expression to apply

captureindex

-

0

Index of the group to return. 0 returns the whole match of the expression, and the capture groups start at 1.

capturepattern

-

-

A template used to build the output from several groups at once, referencing them with \0, \1, \2, and so on. When set, captureindex is ignored.

When the regular expression does not match at all, or when captureindex points past the last group, the transformer returns an empty string rather than failing.

transformers:
  # "jenkins-2.375.1" -> "2.375.1"
  - findsubmatch:
      pattern: 'jenkins-(\d+\.\d+\.\d+)'
      captureindex: 1
transformers:
  # "1.2.3" -> "major=1 minor=2 patch=3"
  - findsubmatch:
      pattern: '(\d+)\.(\d+)\.(\d+)'
      capturepattern: 'major=\1 minor=\2 patch=\3'

JsonMatch

A jsonmatch rule parses the incoming value as JSON and extracts a value using a dasel selector. It is typically used behind a source returning a raw JSON payload, such as an HTTP response.

NameRequiredDefaultDescription

key

✔

-

The dasel selector to evaluate, for example .tag_name or .assets.[0].name

nomatchresult

-

-

What to return when the selector matches nothing. Use the literal <input> to return the value unchanged, <blank> to return an empty string, or any other string to return it as is. When unset, no match is an error.

joinmultiplematches

-

-

When the selector matches several values, join them with this separator

multiplematchselector

-

-

When the selector matches several values, pick one: first, last, or an index such as [0] or [-1] counting from the end

Important
When the selector matches several values and neither joinmultiplematches nor multiplematchselector is set, the transformer fails.
sources:
  latestRelease:
    kind: http
    spec:
      # The "http" source returns the raw response body
      url: https://api.github.com/repos/updatecli/updatecli/releases/latest
    transformers:
      - jsonmatch:
          key: .tag_name
      - trimprefix: "v"

Examples

Chaining transformers

Each list entry receives the output of the previous one. Given a source returning jenkins-2.375.1:

updatecli.yaml
sources:
  default:
    name: "Get latest Jenkins weekly version"
    kind: jenkins
    spec:
      release: weekly
    transformers:
      # "jenkins-2.375.1" -> "2.375.1"
      - trimprefix: "jenkins-"
      # "2.375.1" -> "2.376.0"
      - semverinc: "minor"
      # "2.376.0" -> "jenkins/jenkins:2.376.0-jdk17"
      - addprefix: "jenkins/jenkins:"
      - addsuffix: "-jdk17"

The output, jenkins/jenkins:2.376.0-jdk17, is a valid Docker image name usable by the later stages.

Preparing a value for a Docker tag

quote and unquote are convenient when the target file expects a quoted string:

sources:
  version:
    kind: shell
    spec:
      command: echo 1.2.3
    transformers:
      - addprefix: "v"
      # -> "v1.2.3" including the double quotes
      - quote: true

Go Further

  • To know more about how a source produces the value being transformed source

  • To know more about selecting a version before transforming it version filter

Last updated on July 30, 2026
Prev
Scm
Next
Docker Image