[Feature]: Gitlab CI Support

未关闭
#12,078 5 条评论 2 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
5/5
预计耗时
一周以上
新手友好度
35/100
Issue 类型
功能
描述清晰度
需要澄清
活跃度
活跃
技术栈
docker, gitlab, java
领域
ci-cd, devops, testing

调研方向

首先检查 TestcontainersConfiguration 以及现有的 Docker 环境检测和连接设置。确定 GitLab CI 服务发现、Docker 主机选择、TLS 证书和回退行为应如何集成到该库中,然后验证 issue 中描述的配置和 CI 场景。

由索引模型根据 Issue 内容生成。

描述

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

主要语言
Java
星标
8.8k
派生
2k
平均合并
5 天 21 小时
30 天内合并 PR
15

环境准备

在 Codespaces 中打开

在浏览器里用你自己的 GitHub 账号启动这个项目的开发容器。

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

testcontainers/testcontainers-java 的其他 Issue

查看 testcontainers/testcontainers-java 的全部 Issue

相似的 Issue

更多 Java Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。