yq: String Functions for CI Values
yq offers string functions like split, join, sub, test, and case conversion to reshape values inside a pipeline.
Tags, labels, and names often need slicing or rewriting: split a "name:tag" image, replace a prefix, or normalize case. yq has the string toolkit for it.
What it does
yq provides split(sep), join(sep), sub(regex; replacement) for substitution, test(regex) for matching, and upcase/downcase for case. These operate on string nodes and compose with path expressions, so you can transform a value and assign the result back with -i.
Common usage
# take the tag portion of "registry/app:1.4.0"
yq '.image | split(":") | .[-1]' values.yaml
# replace a registry prefix
yq -i '.image |= sub("^old-registry/"; "new-registry/")' values.yaml
# uppercase an environment name
yq '.env | upcase' values.yamlString functions
| Function | What it does |
|---|---|
| split("sep") | Split a string into an array |
| join("sep") | Join an array into a string |
| sub("re"; "x") | Regex substitute (first match) |
| test("re") | Boolean: does the string match |
| upcase / downcase | Change case |
| "prefix-" + . | Concatenate strings |
In CI
Extract a tag into an output: TAG=$(yq '.image | split(":") | .[-1]' values.yaml); echo "tag=$TAG" >> "$GITHUB_OUTPUT". sub() is handy for retagging an image registry across a manifest in one edit.
Common errors in CI
split or sub on a non-string (a number or null) errors; coerce or guard the type first. sub takes a semicolon between pattern and replacement, sub("a"; "b"); a comma is a syntax error. These string functions share jq names, so the same expression may run on kislyuk/yq too, but only Go yq persists the change with -i.