[Feature]: Gitlab CI Support

Offen
#12,078 5 Kommentare 2 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Maintainer antworten meist innerhalb von 1 Tag

Dieses Issue hat noch niemand übernommen.

Bewertung

Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Anfängerfreundlichkeit
35/100
Issue-Typ
Feature
Klarheit
Muss geklärt werden
Aktivitätsstatus
Aktiv
Tech-Stack
docker, gitlab, java
Bereich
ci-cd, devops, testing

Rechercherichtung

Beginne mit der Überprüfung von TestcontainersConfiguration und der bestehenden Erkennung der Docker-Umgebung sowie dem Verbindungsaufbau. Lege fest, wie die Service-Erkennung in GitLab CI, die Auswahl des Docker-Hosts, TLS-Zertifikate und das Fallback-Verhalten in die Bibliothek integriert werden sollen, und überprüfe anschließend die in der issue beschriebenen Konfigurationen und CI-Szenarien.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

type/feature
Module

No response

Problem

In many GitLab CI pipelines, integration tests that rely on Testcontainers need a running Docker daemon. The typical workaround is:

  1. Run a docker:dind service in privileged mode
  2. Mount the host Docker socket into the test container
  3. Set DOCKER_HOST=unix:///var/run/docker.sock in the test environment

This approach has several pain points:

Issue Impact
Privileged mode Requiresprivileged: truein the job, which is disallowed in many shared runners for security reasons.
Docker socket exposure Mounting/var/run/docker.sockcan inadvertently grant the test container full control over the host Docker daemon.
Port collisions & networking The test container must be on the same network namespace as thedocker:dindservice, which is fragile and hard to debug.
Resource overhead Each job starts a full DinD daemon, increasing build time and memory usage.
Complex configuration Users must remember to setDOCKER_HOST,DOCKER_TLS_VERIFY, etc., which is error‑prone.

A native GitLab CI services integration would eliminate the need for privileged mode, reduce configuration complexity, and improve security:

  • Security – Avoid exposing the host Docker socket or running privileged containers.
  • Simplicity – A single configuration flag should be sufficient to enable CI‑specific behavior.
  • Performance – Reuse the GitLab CI service container’s Docker daemon instead of launching a new DinD instance per job.
  • Consistency – Tests run in CI will mirror local development environments that use Testcontainers without any special CI configuration.
Solution
Add a new configuration option to the `Testcontainers` Java library (and analogous options for other languages) that allows the user to specify a GitLab CI service name and network alias. Example (Java):
TestcontainersConfiguration.getInstance()
           .withGitLabService("docker:dind", "docker");
Internally, Testcontainers will:

1.  Detect that it is running inside a GitLab CI job (e.g., by checking `CI` environment variable).
2.  Resolve the service container’s IP address via the GitLab CI network (`docker` alias).
3.  Set `DOCKER_HOST=tcp://<service-ip>:2375` (or `2376` if TLS is enabled).
4.  Optionally configure TLS certificates if the service exposes them.
Runtime Behavior
-   No privileged mode – The job can run without `privileged: true`.
-   Automatic network discovery – Testcontainers will query the GitLab CI network for the service alias.
-   TLS support – If the GitLab service exposes TLS, the library can automatically pick up the certificates from known paths (`/etc/docker/certs.d/`).
Fallback
If the CI environment is not detected or the service is missing, Testcontainers will fall back to its normal local Docker daemon strategy, preserving backward compatibility.
Benefit
| Category | Impact |
| --- | --- |
| Security | Positive – reduces privileged execution and socket exposure. |
| Performance | Slightly better – reusing the CI service container avoids launching a separate DinD daemon. |
| Developer Experience | Positive – fewer environment variables, clearer CI configuration. |
| Maintenance | Minimal – only a small API addition and a few environment checks. |
| Compatibility | Backward compatible; old jobs continue to work unchanged. |
Alternatives
  • Priviledge DinD Runner in Kubernetes
Would you like to help contributing this feature?

Yes

Vorherrschende Sprache
Java
Sterne
8.8k
Forks
2k
Ø Merge
5 T. 21 Std.
Gemergte PRs (30 T.)
15

Entwicklungsumgebung

In Codespaces öffnen

Startet den Dev-Container des Projekts im Browser, mit Ihrem eigenen GitHub-Konto.

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus testcontainers/testcontainers-java

Alle Issues in testcontainers/testcontainers-java

Ähnliche Issues

Weitere Issues zu Java

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.