yq eval Command Reference

Query and edit YAML files in deploy pipelines.

yq eval applies an expression to YAML, reading a value or editing the document. In CI it is the standard tool for bumping image tags and patching manifests without a templating engine.

What it does

yq eval (the Go yq by mikefarah) evaluates a path or jq-like expression against a YAML document, printing the result or, with -i, rewriting the file in place. It is the dependable way to read or mutate manifests in a script.

Common flags and usage

-i / --inplace: edit the file in place
eval '.path' FILE: read a value at a path
eval '.path = "value"' -i FILE: set a value
-o=json: output JSON instead of YAML
env(VAR) and strenv(VAR): interpolate environment variables
eval-all: operate across multiple documents at once

Example

shell

- name: Bump image tag
  run: |
    yq eval -i \
      '.spec.template.spec.containers[0].image = strenv(IMAGE)' \
      k8s/deployment.yaml
  env:
    IMAGE: "myrepo/app:${{ github.sha }}"

In CI

Use yq eval -i with strenv(VAR) to inject build values (like an image tag) into a manifest safely, avoiding fragile sed substitutions. Note that the Go yq and the Python yq differ in syntax; pin the Go version in your runner image so expressions behave consistently.

Key takeaways

yq eval reads or edits YAML; -i rewrites the file in place.
Use strenv(VAR) to inject env values instead of brittle sed edits.
Pin the Go yq (mikefarah) so expression syntax is consistent in CI.