How to Use Testcontainers Cloud in CI

Testcontainers Cloud runs your containers on remote workers, so the CI runner needs a token instead of a local Docker daemon.

Add the Testcontainers Cloud setup action with a TC_CLOUD_TOKEN. It starts an agent that redirects container operations to the cloud, which helps on runners without local Docker or when you want a warm image cache.

Steps

• Create a Testcontainers Cloud service account token.
• Store it as the TC_CLOUD_TOKEN secret.
• Run the cloud setup action before your tests.
• Run tests unchanged; containers execute in the cloud.

Workflow

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Testcontainers Cloud
        uses: atomicjar/testcontainers-cloud-setup-action@main
        with:
          token: ${{ secrets.TC_CLOUD_TOKEN }}
      - run: mvn -B verify

Gotchas

• Test code is unchanged; only where containers run moves to the cloud.
• A warm cloud image cache reduces pull time versus pulling on every ephemeral runner.

Related guides