Testcontainers CI Guide: GitHub Actions, GitLab CI and Jenkins

Runner Requirements for a Testcontainers CI Job

Testcontainers starts real databases, brokers and other dependencies in throwaway containers for integration testing, so it needs a Docker-API compatible daemon wherever the tests run. Before writing pipeline YAML, check how the runner answers each of these:

• A reachable daemon - Testcontainers reads DOCKER_HOST and its TLS companions before it falls back to the local default, so a job that runs inside a container has to be handed a socket or a TCP address.
• Linux containers - the Testcontainers for .NET CI page notes that Windows agents run the Docker Windows engine, which cannot run Linux containers, so keep Linux images on Linux runners.
• A route to mapped ports - the Testcontainers networking docs say each exposed port is published on a random free host port to avoid collisions between parallel runs, so the test process must be able to reach the host that publishes it.
• Room for Ryuk - the Ryuk cleanup container mounts the Docker socket and on some runtimes must run privileged, so a runner that blocks both needs another cleanup plan.

If you are still deciding which tests belong in this layer, the comparison of integration testing tools groups Testcontainers, WireMock and API-level tools by the boundary each one tests.

Docker-in-Docker vs Socket Mounting for Testcontainers

When the CI job itself runs in a container, as on GitLab's Docker executor or in a Jenkins docker agent, Testcontainers needs a daemon from outside that container. It can borrow the host's daemon through a mounted socket, or use a private daemon that a Docker-in-Docker container runs beside the job.

• Socket mounting - the job mounts /var/run/docker.sock, so every container Testcontainers starts is a sibling on the host daemon. The Testcontainers patterns for running tests inside a Docker container say the library detects that it runs in a container and uses the default gateway's IP instead of localhost; bind mounts also need the source directory mounted at the same path inside the job.
• Docker-in-Docker - a docker:dind service runs a separate daemon for each job, so parallel jobs cannot see each other's containers, and the daemon's images and containers go away with the job. It needs a privileged container, and its image cache starts empty every time.

The same patterns page says Docker-in-Docker is generally considered an instrument of last resort, yet it is the route GitLab.com's privileged hosted runners support. GitLab's page Use Docker to build Docker images spells out the cost of the other route: sharing the daemon effectively disables the container's security mechanisms and exposes the host to privilege escalation, and the containers it starts are siblings of the runner.

Neither route sandboxes a job, since one shares the host daemon and the other runs privileged, so keep both for trusted code and run forks on runners that are discarded after each job. Prefer copying files into containers over bind mounts as well: the Testcontainers files docs recommend copying for portability across Docker environments, and it sidesteps the same-path rule.

How to Run Testcontainers on GitHub Actions

GitHub-hosted Ubuntu runners need no Testcontainers settings: the Testcontainers for .NET CI page says GitHub-hosted runners come with Docker pre-installed, as Microsoft-hosted agents do. Trouble starts with the runner label, because not every GitHub-hosted image can run Linux containers.

// Which GitHub-hosted runner images ship a Docker daemon?
const base = "https://raw.githubusercontent.com/actions/" +
  "runner-images/main/images/";
const images = {
  "ubuntu-24.04": "ubuntu/Ubuntu2404-Readme.md",
  "ubuntu-26.04": "ubuntu/Ubuntu2604-Readme.md",
  "ubuntu-slim": "ubuntu-slim/ubuntu-slim-Readme.md",
  "windows-2025": "windows/Windows2025-Readme.md",
  "macos-15": "macos/macos-15-arm64-Readme.md",
};
for (const [label, path] of Object.entries(images)) {
  const text = await (await fetch(base + path)).text();
  const docker = text.split("\n")
    .filter((l) => /^- Docker (Client|Server|\d)/.test(l))
    .map((l) => l.slice(9));
  console.log(label.padEnd(13) + (docker.join(", ") || "none"));
}

ubuntu-24.04 Client 28.0.4, Server 28.0.4
ubuntu-26.04 Client 29.4.2, Server 29.4.2
ubuntu-slim  Client 29.9.2
windows-2025 29.7.2
macos-15     none

name: integration-tests
on: [push, pull_request]

jobs:
  integration-tests:
    # Pinned: ubuntu-latest is moving to Ubuntu 26.04
    runs-on: ubuntu-24.04
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-java@v6
        with:
          distribution: temurin
          java-version: '21'
          cache: maven
      # Forked pull requests get no secrets, so they
      # skip the login and pull anonymously
      - if: github.event.pull_request.head.repo.fork != true
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
      - name: Pull the pinned test images
        run: |
          docker pull postgres:18.6-alpine
          docker pull redis:7.4-alpine
      - name: Run the Testcontainers tests
        run: mvn -B verify

How to Run Testcontainers in GitLab CI

GitLab's Docker executor runs every job inside a container, so a Testcontainers job there uses one of the two patterns above. GitLab's hosted runner docs say runners tagged saas-linux, including the default saas-linux-small-amd64, run in privileged mode, while runners with the gitlab-org tag cannot run Docker-in-Docker builds.

The Testcontainers GitLab CI guide gives the Docker-in-Docker settings: point DOCKER_HOST at tcp://docker:2375, set DOCKER_TLS_CERTDIR to an empty string and start the service with --tls=false. Without that flag, Docker delays its startup when the API listens on a network address without TLS, and jobs that call it right away can fail.

integration-tests:
  stage: test
  image: maven:3.9-eclipse-temurin-21
  services:
    # Pinned: plain docker:dind follows each new
    # Docker major release
    - name: docker:29-dind
      alias: docker
      command: ["--tls=false"]
  variables:
    DOCKER_HOST: "tcp://docker:2375"
    DOCKER_TLS_CERTDIR: ""
    DOCKER_DRIVER: overlay2
  script:
    - mvn -B verify

Pin the service tag, because plain docker:dind follows each new Docker release, which is how jobs met Engine 29 the day its dind image was published. Raise the tag only after the Testcontainers version in the build file supports the new engine.

On a self-managed runner, the socket route is a runner setting: add /var/run/docker.sock:/var/run/docker.sock to volumes under [runners.docker] in config.toml, then set TESTCONTAINERS_HOST_OVERRIDE in the job's variables to the Docker host's IP, or host.docker.internal on Windows and macOS. The GitLab CI guide warns that without it Testcontainers resolves the wrong IP for the Docker host, which will likely lead to failing tests.

For Docker Hub limits, put a Docker config JSON in a masked DOCKER_AUTH_CONFIG CI/CD variable, the name GitLab's runner uses for registry credentials. Every Testcontainers library reads the same variable for the images it pulls.

How to Run Testcontainers in a Jenkins Pipeline

The Testcontainers CI docs have no Jenkins page, but the patterns page names running everything in containers on Jenkins as a use for the socket-mounting pattern. Which setup applies depends on the agent:

• An agent with Docker installed - a VM or bare-metal agent works like a laptop once its user can reach the daemon socket. Docker's post-install guide warns that the docker group grants root-level privileges, so keep these agents for trusted jobs.
• A docker agent with the socket mounted - Jenkins' Docker Pipeline plugin runs the stages inside an image you choose, and mounting the agent's socket gives Testcontainers sibling containers on the agent's daemon. Check that plugin's compatibility each time you upgrade Jenkins, because the docker agent in the pipeline below depends on it.
• Kubernetes pod agents - pods usually have no Docker daemon to borrow, so add a privileged docker:dind sidecar to the pod template and share its socket with the build container through an emptyDir volume, the layout of the Tekton example in the Testcontainers docs.

pipeline {
  agent {
    docker {
      image 'maven:3.9-eclipse-temurin-21'
      // Mount the agent's daemon socket. If the build
      // user cannot open it, add the socket's group ID
      // (stat -c %g /var/run/docker.sock on the agent)
      args '-v /var/run/docker.sock:/var/run/docker.sock --group-add 999'
    }
  }
  options {
    timeout(time: 20, unit: 'MINUTES')
  }
  stages {
    stage('Testcontainers tests') {
      steps {
        sh 'mvn -B verify'
      }
    }
  }
}

If containers start but connections to their mapped ports time out, the build container cannot reach the gateway address Testcontainers picked, so set TESTCONTAINERS_HOST_OVERRIDE to an address of the agent host that it can reach. The Jenkins pipeline tutorial covers the agent, options and stages blocks this file uses.

Ryuk, Reuse and Container Cleanup in CI

Ryuk is the resource reaper used across the Testcontainers language implementations: it removes the containers, networks and volumes a test session created, found by the labels Testcontainers adds, even when a test never called stop or terminate. Testcontainers for Go's garbage collector docs describe it that way and recommend disabling it only for CI services that have their own mechanism to clean up resources.

• Keep it on - wherever the daemon outlives the job, such as a socket-mounted runner or a long-lived Jenkins agent, because leftovers there pile up across builds.
• Safe to turn off - where the CI system already discards everything after the job, such as a Docker-in-Docker service, or where Ryuk cannot run at all: the Testcontainers for .NET CI page sets TESTCONTAINERS_RYUK_DISABLED=true for Bitbucket Pipelines, which does not support Ryuk.
• Run it privileged - some runtimes need the privileged flag for Ryuk, so try the privileged variable from the settings table before switching cleanup off.

A blocked Ryuk shows up in Java logs as "Can not connect to Ryuk at" followed by a host and port, and the run then fails with "Could not connect to Ryuk at". Check that the socket path Ryuk mounts exists on the daemon's host, which TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE sets, then whether the runner allows privileged containers.

Reusable containers work against that cleanup. The Testcontainers for Java reusable containers page marks the feature experimental, says reused containers keep running after the tests finish and states that they are not suited for CI usage. Leave TESTCONTAINERS_REUSE_ENABLE unset in pipelines and keep reuse for local runs, set in ~/.testcontainers.properties.

Timeouts and Flaky Testcontainers Runs in CI

Each GitHub-hosted job gets a new virtual machine and each Docker-in-Docker service an empty daemon, so a suite on those runners pulls every image on every run. Docker Hub's pull usage and limits page caps unauthenticated pulls at 100 per IPv4 address or IPv6 /64 subnet every 6 hours and authenticated Personal accounts at 200, and it warns that a shared CI address can trigger abuse rate limiting even for authenticated pulls.

• Log in - authenticate before the tests start, because every Testcontainers library reads registry credentials from DOCKER_AUTH_CONFIG or from the Docker config file that docker login writes.
• Mirror - set TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX to a registry mirror so Docker Hub images are pulled through your own registry.
• Pin and pre-pull - pull exact tags in a step of their own and never test against latest, which can change the image under a passing suite.

Then give containers enough time on a cold, shared runner. The Testcontainers wait strategy docs say a container gets up to 60 seconds for its first mapped port to start listening, that withStartupTimeout() changes the limit, and that waitingFor() swaps the port check for an HTTP, health check or log message wait.

Pulls have limits of their own: the Testcontainers for Java configuration docs time out a pull after 120 seconds and abort one that stalls for 30, both adjustable through pull.timeout and pull.pause.timeout. This test sizes both containers for a cold runner:

import java.time.Duration;
import org.junit.jupiter.api.Test;
import org.testcontainers.containers.GenericContainer;
import org.testcontainers.containers.wait.strategy.Wait;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import org.testcontainers.postgresql.PostgreSQLContainer;

@Testcontainers
class OrderRepositoryTest {

  // The module waits for its "ready" log line for
  // 60 s by default; give a cold runner longer.
  @Container
  static PostgreSQLContainer postgres =
      new PostgreSQLContainer("postgres:18.6-alpine")
          .withStartupTimeout(Duration.ofMinutes(3));

  // A generic container needs its own readiness check.
  @Container
  static GenericContainer<?> redis =
      new GenericContainer<>("redis:7.4-alpine")
          .withExposedPorts(6379)
          .waitingFor(Wait.forLogMessage(
              ".*Ready to accept connections.*\\n", 1))
          .withStartupTimeout(Duration.ofMinutes(2));

  @Test
  void savesAnOrder() {
    // Ports are assigned at startup: never hardcode
    // localhost:5432 or localhost:6379.
    String jdbcUrl = postgres.getJdbcUrl();
    String redisHost = redis.getHost();
    int redisPort = redis.getMappedPort(6379);
    // ...connect with these values and assert
  }
}

A run that fails, then passes on retry with no change, matches the definition of flaky tests, and in a Testcontainers suite the image pulls and container start times are the first things to check. GenericContainer also offers withStartupAttempts() for containers whose startup is unreliable in ways that should not affect the test outcome, though a retry hides a slow pull instead of fixing it.

Testcontainers CI Errors and Their Fixes

These messages come from the Testcontainers for Java source and from Docker's docs, so a CI log can be searched for them directly. The left column holds the stable start of each message; the rest varies by host, port or image.

Browser Tests on TestMu AI Beside Testcontainers

Testcontainers can run the browser layer as well: its WebDriver containers module starts Chrome, Firefox or Edge from SeleniumHQ's docker-selenium images as one more container on the runner. That puts the browsers on the same small machine as the databases, the arrangement you get when you run Selenium tests in Docker on one host.

TestMu AI takes the browsers off the runner. Its cloud grid runs Selenium, Playwright, Cypress and Puppeteer suites across 3,000+ browser and OS combinations in parallel, records video, console and network logs for each session, and reaches an app the CI job serves on localhost through its tunnel.

The Docker tunnel image runs that tunnel as a container, and on Linux the --network host flag lets it reach services on the runner through localhost. Added to the same workflow file, this job opens the tunnel after the integration tests pass, waits on the tunnel's info API the way TestMu AI's Google Cloud Build example does, then runs the browser profile:

jobs:
  browser-tests:
    needs: integration-tests
    runs-on: ubuntu-24.04
    env:
      LT_USERNAME: ${{ secrets.LT_USERNAME }}
      LT_ACCESS_KEY: ${{ secrets.LT_ACCESS_KEY }}
      LT_TUNNEL_NAME: ci-${{ github.run_id }}
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-java@v6
        with:
          distribution: temurin
          java-version: '21'
          cache: maven
      - name: Start the app on localhost:8080
        run: docker compose up -d --wait
      - name: Open the TestMu AI tunnel
        run: |
          docker run -d --network host lambdatest/tunnel \
            --user "$LT_USERNAME" --key "$LT_ACCESS_KEY" \
            --tunnelName "$LT_TUNNEL_NAME" \
            --infoAPIPort 8000
          curl -s --retry-connrefused --retry 30 \
            --retry-delay 2 --max-time 5 \
            http://127.0.0.1:8000/api/v1.0/info
          # The documented Cloud Build example also waits here
          sleep 20
      - name: Run the browser tests on TestMu AI
        run: mvn -B -Pbrowser verify

The browser test names the same tunnel in its LT:Options capabilities, which is how the cloud session reaches the runner's localhost:

ChromeOptions options = new ChromeOptions();
options.setPlatformName("Windows 11");
options.setBrowserVersion("latest");

HashMap<String, Object> lt = new HashMap<>();
lt.put("build", "browser " + System.getenv("GITHUB_RUN_ID"));
lt.put("tunnel", true);
lt.put("tunnelName", System.getenv("LT_TUNNEL_NAME"));
lt.put("w3c", true);
options.setCapability("LT:Options", lt);

String grid = "https://" + System.getenv("LT_USERNAME") + ":"
    + System.getenv("LT_ACCESS_KEY")
    + "@hub.lambdatest.com/wd/hub";
WebDriver driver = new RemoteWebDriver(
    URI.create(grid).toURL(), options);
// The cloud browser opens the runner's app through the tunnel
driver.get("http://localhost:8080/");

Conclusion

Start with the runner: run the image check above against the label your workflow uses, then pin that label or the docker:dind tag, so the next Docker major reaches your Testcontainers CI job on a day you pick. Before that day, upgrade Testcontainers to a release that supports the new engine, keep Ryuk on wherever the daemon outlives the job and keep reusable containers out of pipelines.

When the browser layer outgrows the runner, move it to TestMu AI's test automation cloud, and follow the guide to test locally hosted websites with Selenium to wire the tunnel into the browser job.