Running Testcontainers in GitHub Actions

Run Testcontainers integration tests in CI against real Postgres, Redis, or Kafka.

Testcontainers spins up throwaway Docker containers (databases, brokers, anything) for integration tests. GitHub-hosted Linux runners include Docker, so it mostly works out of the box. The main job is making sure the Docker daemon is reachable and images are pulled efficiently.

What you need

Docker available on the runner (default on ubuntu-latest).
A Testcontainers library for your language.
Tests that start containers in setup.

The workflow

On Linux runners, Docker is present, so just run your tests.

.github/workflows/ci.yml

- uses: actions/checkout@v4
- uses: actions/setup-java@v4
  with:
    distribution: temurin
    java-version: 21
- run: ./gradlew test
  env:
    TESTCONTAINERS_RYUK_DISABLED: "false"

Common gotchas

Testcontainers does not work on macOS/Windows hosted runners (no Docker daemon).
Image pulls dominate runtime; use a registry mirror or warm runners to avoid cold pulls.
Ryuk cleanup needs Docker socket access - keep it enabled unless your runner blocks it.

Key takeaways

Testcontainers needs a Docker daemon - use Linux runners.
Image pulls dominate cold runs; cache or warm them.
Keep Ryuk enabled for reliable container cleanup.