yq: Read a Value at a Path from YAML
yq evaluates a path expression like .a.b.c against a YAML or JSON document and prints the matching value.
Reading a single field is the most common yq task in CI: pull a version, an image tag, or a replica count out of a manifest. The Go yq syntax is jq-like but not identical.
What it does
With mikefarah/yq (Go), yq evaluates a path expression against the document and prints the result to stdout. A bare filter like yq '.image.tag' file.yaml reads that path. With no file it reads stdin. The expression always starts with a leading dot for the root.
Common usage
yq '.metadata.name' deployment.yaml
yq '.spec.replicas' deployment.yaml
cat deployment.yaml | yq '.spec.template.spec.containers[0].image'Path expressions
| Expression | What it returns |
|---|---|
| .a.b | Value of nested key b under a |
| .a["b-c"] | Key with a dash or special char (quote it) |
| .list[0] | First element of an array |
| .list[-1] | Last element of an array |
| .a.b // "default" | Value, or "default" if a.b is null/missing |
| ... comments="" | Strip comments from the output |
In CI
To read a value into a step output, capture it: TAG=$(yq '.image.tag' values.yaml) then echo "tag=$TAG" >> "$GITHUB_OUTPUT". Add -r is NOT needed in Go yq (scalars print raw already); -r is a Python yq flag.
Common errors in CI
"yq: command not found" means yq is not installed on the runner (see the install page). If yq prints {"a": ...} JSON or rejects '.a.b' wanting '.["a"]', you are on kislyuk/yq (Python), which wraps jq and needs a filter plus a file argument, e.g. yq '.a.b' file.yaml with jq semantics. Run yq --version: Go yq prints "yq (https://github.com/mikefarah/yq/) version v4.x".