yq: Edit docker-compose Files in CI
yq edits docker-compose.yml in place, updating a service image, port, or environment variable before bringing the stack up.
CI pipelines that spin up a compose stack often patch it first: pin an image, add an env var, or change a port. The services map and the two environment formats are the things to know.
What it does
A compose file keys services by name under .services. yq edits a field on a service with assignment and -i. The environment field can be a map (KEY: value) or a list ("KEY=value"); the edit syntax differs between the two, so check which form the file uses.
Common usage
# pin a service image
yq -i '.services.web.image = "myapp:1.4.0"' docker-compose.yml
# add an env var when environment is a map
yq -i '.services.web.environment.LOG_LEVEL = "debug"' docker-compose.yml
# add an env var when environment is a list
yq -i '.services.web.environment += ["LOG_LEVEL=debug"]' docker-compose.ymlCompose paths
| Path | What it targets |
|---|---|
| .services.web.image | The image of service "web" |
| .services.web.ports[0] | The first published port |
| .services.web.environment.KEY | Env var (map form) |
| .services.web.environment[+] | Append env var (list form) |
| .services | keys | List all service names |
| del(.services.debug) | Remove a service |
In CI
Pin the image to the freshly built tag before docker compose up: yq -i '.services.web.image = strenv(IMAGE)' docker-compose.yml. Detect the environment format first with yq '.services.web.environment | type' so you append to a list versus set a map key correctly.
Common errors in CI
Using the map form (.environment.KEY = ...) on a file where environment is a list creates a new key on a sequence and produces invalid compose; match the file's format. += on a map environment errors because it expects an array. As always, a no-op -i edit or "command not found" points at the wrong yq or a missing install.