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 testAlternatively, 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-*.xmlThe 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: 15mThe 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 jenkinsParallelism 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 }}/4Sharding 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 runnerEnvironment 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=0Common 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:
container.stop()inafterAll/afterEachhooks- Ryuk (resource reaper) — a background container that removes orphaned containers
In CI, always verify containers are cleaned up. Check with:
docker ps -a | grep testcontainersIf 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.