Testcontainers in CI/CD: GitHub Actions, GitLab CI, and Docker-in-Docker

Testcontainers in CI/CD: GitHub Actions, GitLab CI, and Docker-in-Docker

Testcontainers works locally when Docker is available, but CI pipelines need careful configuration. The requirements: Docker socket access, image caching, and timeouts that accommodate container startup. This guide covers setup for the most common CI systems.

GitHub Actions

GitHub Actions runners (ubuntu-latest) include Docker pre-installed. Testcontainers works without any extra configuration:

name: Integration Tests
on: [push, pull_request]

jobs:
  integration-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'

      - name: Pre-pull Docker images
        run: |
          docker pull postgres:16
          docker pull redis:7-alpine
          docker pull confluentinc/cp-kafka:7.5.0

      - name: Run integration tests
        run: ./mvnw test -Dtest="*IntegrationTest"
        timeout-minutes: 15

      - name: Upload test reports
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: test-reports
          path: target/surefire-reports/

Pre-pulling images is critical. Without it, the first test that pulls postgres:16 adds 30–60 seconds. Pre-pulling is sequential but happens before tests start — total time is often lower than letting each container pull independently.

Caching Docker Images in GitHub Actions

GitHub Actions doesn't have a built-in Docker image cache, but you can save/restore images via the Actions cache:

- name: Cache Docker images
  uses: ScribeMD/docker-cache@0.5.0
  with:
    key: docker-${{ runner.os }}-${{ hashFiles('**/docker-compose*.yml', '**/Dockerfile*') }}

- name: Run tests
  run: ./mvnw test

Alternatively, cache the Testcontainers local image cache directory:

- name: Cache Testcontainers images
  uses: actions/cache@v4
  with:
    path: ~/.testcontainers
    key: testcontainers-${{ runner.os }}-${{ hashFiles('**/pom.xml') }}

Node.js on GitHub Actions

name: Node Integration Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - run: npm ci

      - name: Pre-pull images
        run: |
          docker pull postgres:16
          docker pull redis:7-alpine

      - name: Run integration tests
        run: npm run test:integration
        env:
          NODE_ENV: test
        timeout-minutes: 10
// package.json
{
  "scripts": {
    "test": "vitest run",
    "test:integration": "vitest run --config vitest.integration.config.ts"
  }
}

GitLab CI

GitLab CI requires Docker-in-Docker (DinD) for Testcontainers:

# .gitlab-ci.yml
integration-tests:
  image: maven:3.9-eclipse-temurin-21
  services:
    - docker:dind
  variables:
    DOCKER_HOST: tcp://docker:2376
    DOCKER_TLS_CERTDIR: "/certs"
    DOCKER_TLS_VERIFY: 1
    DOCKER_CERT_PATH: "/certs/client"
    TESTCONTAINERS_HOST_OVERRIDE: "docker"
  before_script:
    - docker pull postgres:16
    - docker pull redis:7-alpine
  script:
    - mvn test -Dtest="*IntegrationTest"
  artifacts:
    when: always
    reports:
      junit:
        - target/surefire-reports/TEST-*.xml

The TESTCONTAINERS_HOST_OVERRIDE variable tells Testcontainers to use the DinD service hostname (docker) instead of localhost when computing mapped port hostnames.

CircleCI

CircleCI uses the machine executor for Docker support:

# .circleci/config.yml
version: 2.1

jobs:
  integration-tests:
    machine:
      image: ubuntu-2204:current
    steps:
      - checkout

      - run:
          name: Pre-pull Docker images
          command: |
            docker pull postgres:16
            docker pull redis:7-alpine

      - run:
          name: Run integration tests
          command: ./mvnw test -Dtest="*IntegrationTest"
          no_output_timeout: 15m

The machine executor has full Docker support. The docker executor (container-in-container) is more complex — prefer machine for Testcontainers.

Jenkins

// Jenkinsfile
pipeline {
    agent {
        label 'docker'  // Jenkins node with Docker installed
    }

    stages {
        stage('Integration Tests') {
            steps {
                sh 'docker pull postgres:16'
                sh 'docker pull redis:7-alpine'
                sh './mvnw test -Dtest="*IntegrationTest" -Dmaven.test.failure.ignore=true'
            }
            post {
                always {
                    junit 'target/surefire-reports/*.xml'
                }
            }
        }
    }
}

Jenkins agents need Docker installed and the Jenkins user must be in the docker group:

sudo usermod -aG docker jenkins

Parallelism in CI

Running integration tests in parallel reduces total time. Two strategies:

Parallel test classes (single machine):

# GitHub Actions matrix strategy
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        test-group: [auth, orders, payments, notifications]

    steps:
      - run: ./mvnw test -Dgroups=${{ matrix.test-group }}

Shard by test file (Node.js):

strategy:
  matrix:
    shard: [1, 2, 3, 4]

steps:
  - run: npx vitest run --shard=${{ matrix.shard }}/4

Sharding requires each shard to start its own containers. Startup cost is paid per shard, but total elapsed time drops by the shard count.

Testcontainers Cloud

Testcontainers Cloud runs containers on remote infrastructure instead of the CI runner's local Docker:

# Install the agent
curl -fsSL https://get.testcontainers.cloud/bash | bash

# Or install via GitHub Actions
- uses: atomicjar/testcontainers-cloud-setup-action@v1
  with:
    token: ${{ secrets.TC_CLOUD_TOKEN }}

Benefits:

  • Works in environments without Docker (serverless CI runners, minimal containers)
  • Consistent container performance regardless of CI runner size
  • No Docker-in-Docker complexity
  • Container lifecycle managed externally
# GitHub Actions with Testcontainers Cloud
- name: Setup Testcontainers Cloud
  uses: atomicjar/testcontainers-cloud-setup-action@v1
  with:
    token: ${{ secrets.TC_CLOUD_TOKEN }}

- name: Run integration tests
  run: ./mvnw test
  # No Docker required on the runner

Environment Variables for CI

Testcontainers respects several environment variables useful for CI:

# Disable Ryuk (resource reaper) — useful in some CI environments
TESTCONTAINERS_RYUK_DISABLED=true

# Override Docker host
DOCKER_HOST=tcp://docker:2376

# Override the host Testcontainers uses for port mapping
TESTCONTAINERS_HOST_OVERRIDE=docker

# Use a specific Docker socket
DOCKER_SOCKET_OVERRIDE=/var/run/docker.sock

# Disable pull for already-present images
TESTCONTAINERS_PULL_PAUSE_TIMEOUT=0

Common CI Failures

"Cannot connect to Docker": The CI runner doesn't have Docker. Use a machine executor (CircleCI), ubuntu-latest runner (GitHub Actions), or DinD service (GitLab).

Timeout during container startup: Image pull takes too long. Pre-pull images before running tests, or increase test timeouts.

Port conflicts: Multiple parallel jobs on the same runner conflict on ports. Use random port assignment (the default in Testcontainers) — never hardcode container ports.

Ryuk failures: Ryuk is Testcontainers' resource reaper that cleans up orphaned containers. In some CI environments it fails. Disable with TESTCONTAINERS_RYUK_DISABLED=true and rely on CI job cleanup instead.

"Host not found" in GitLab DinD: Set TESTCONTAINERS_HOST_OVERRIDE=docker to point Testcontainers at the DinD service hostname.

Resource Cleanup

Testcontainers cleans up containers after tests via:

  1. container.stop() in afterAll/afterEach hooks
  2. Ryuk (resource reaper) — a background container that removes orphaned containers

In CI, always verify containers are cleaned up. Check with:

docker ps -a | grep testcontainers

If containers accumulate, Ryuk may be disabled or failing. Enable explicit cleanup in afterAll.

Summary

CI setup for Testcontainers:

CI System Docker Access Key Config
GitHub Actions Built-in (ubuntu-latest) Pre-pull images
GitLab CI DinD service required Set TESTCONTAINERS_HOST_OVERRIDE=docker
CircleCI Machine executor No special config
Jenkins Agent must have Docker Jenkins user in docker group
Any Testcontainers Cloud Token + setup action, no local Docker needed

The most common mistake is forgetting to pre-pull images. Add a docker pull step for every image your tests use — it's the single biggest CI speedup for Testcontainers-based test suites.

Read more

Start now free