How to Layer Multiple Compose Files With -f in CI

Passing several -f files merges them in order, so a small CI override can tweak the base stack without duplicating it.

Keep the shared stack in docker-compose.yml and put CI-only changes in docker-compose.ci.yml, then pass both with -f so later files override earlier ones.

Steps

• Write CI-specific overrides in a second file.
• Pass -f base -f override in that order.
• Later files win on scalar keys; lists and maps merge per Compose rules.

Override file

services:
  api:
    build:
      target: test
    environment:
      LOG_LEVEL: debug
    ports: []

CI step

steps:
  - run: docker compose -f docker-compose.yml -f docker-compose.ci.yml up -d --wait

Gotchas

• Set COMPOSE_FILE=docker-compose.yml:docker-compose.ci.yml to avoid repeating -f on every command.
• Compose merges environment maps but replaces ports list entries, so know which keys merge vs override.

Related guides