How to Add Compose Healthchecks and Gate CI on Them

A healthcheck turns "container started" into "service is actually accepting connections", which is what CI needs before it runs tests.

Add a healthcheck: with a real readiness probe (for example pg_isready or an HTTP curl), then let dependents use depends_on: condition: service_healthy or gate the whole run with --wait.

Steps

• Pick a probe that fails until the service accepts real traffic.
• Tune interval, timeout, retries, and start_period.
• Reference it via depends_on with condition: service_healthy.

Healthcheck

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: test
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 10
      start_period: 10s
  app:
    build: .
    depends_on:
      db:
        condition: service_healthy

Gotchas

• start_period failures do not count against retries, giving slow starters room to boot.
• Use CMD-SHELL when the probe needs shell features like variable expansion or pipes.

Related guides