RFC: standardized project-level image-pinning file + helper API (Renovate-friendly image version tracking)

[mu88]

---

Motivation

Module builders (PostgreSqlBuilder, PlaywrightBuilder, etc.) now require callers to pass the image explicitly — the parameterless constructors with a baked-in default image are deprecated (see discussion #1470). That's a good change: it makes image selection explicit and caller-owned. But it reintroduces a problem the baked-in defaults used to hide: the image reference now lives as a string literal in test source code, which most dependency-update bots (Renovate, Dependabot, …) cannot see or update, since they only scan manifest-like files (.csproj, Dockerfile, docker-compose.yml, …), not arbitrary C#.

Concretely, in my project I had:

new PostgreSqlBuilder("postgres:18-alpine")
new PlaywrightBuilder("mcr.microsoft.com/playwright:v1.63.0-noble")

Renovate has no built-in manager for this. I ended up building my own convention:

1. A small testcontainers.json fixture file listing every image I use, with image/tag split into separate fields (so a generic extraction query doesn't need per-image tag-format regex):

   {
     "postgres": { "image": "postgres", "tag": "18-alpine" },
     "playwright": { "image": "mcr.microsoft.com/playwright", "tag": "v1.63.0-noble" },
     "wiremock": { "image": "sheyenrath/wiremock.net-alpine", "tag": "2.14.0" }
   }

2. A tiny helper class that loads it and exposes GetImageReference(name) => "{image}:{tag}", used at the builder call sites instead of hardcoded strings.
3. A generic Renovate jsonata custom manager (not regex) that matches any file named testcontainers.json and extracts depName/currentValue pairs for the docker datasource — reusable across any repo that adopts the convention, with zero per-repo Renovate config needed beyond including the shared preset.

Working example (both pieces, real commits, public repos):

• App repo adopting the convention: mu88/PodBridge@70f8a09
• Shared Renovate preset with the generic customManager: mu88/common@659c67c

Proposal

Would there be interest in standardizing this pattern at the testcontainers-dotnet level? Possibly cross-language too — I checked testcontainers-java's PostgreSQLContainer, and its parameterless constructor is @Deprecated for the same reason, so at least Java is facing/addressing the identical problem. I haven't checked Go/Python/Node/Rust, so I can't claim they all do the same, but it seems plausible this isn't .NET-specific.

Concretely, that could mean:

• An official, documented file name + JSON schema for project-level image pinning (name TBD — to avoid confusion with the existing user-level ~/.testcontainers.properties, something like testcontainers.images.json might be clearer than my ad-hoc testcontainers.json).
• An optional, opt-in helper (e.g. TestcontainersImages.Get("postgres")) shipped in the core package, so consumers don't need to hand-roll the loader.
• A documented, ready-to-copy Renovate (and maybe Dependabot) custom-manager recipe in the docs, referencing this schema.

Open questions / things I'm genuinely unsure about

• Does this conflict with the direction taken in discussion Should Testcontainers modules drop the default image version? #1470 (explicit-image-only, no more implicit resolution)? I'd argue no — the file is still 100% explicit and caller-owned, just externalized from inline string literals into a sidecar file for tooling visibility, not a hidden default. But keen to hear the maintainers' take.
• Is this in scope for a Docker-orchestration library at all, or is it better left as a documented community pattern/cookbook entry rather than shipped code?
• If there's appetite for this, should it start as a cross-language RFC (given at least Java appears to face the same problem) rather than a .NET-only addition?

Happy to contribute the schema/helper/docs if there's interest — this is already running in production for me, just in userland rather than upstream.

---

This proposal was drafted with AI assistance (GitHub Copilot CLI) based on a real-world implementation I built; I've reviewed and verified its factual claims before posting.

[HofmeisterAn]

What about follow the same approach as our tests, where we read the version number from a Dockerfile:

testcontainers-dotnet/tests/Testcontainers.PostgreSql.Tests/PostgreSqlContainerTest.cs

Line 80 in eeb2616

=> new PostgreSqlBuilder(TestSession.GetImageFromDockerfile());

[mu88]

In general, I don't use Dockerfiles anymore in favor of the .NET SDK Container Building Tools.

But despite that, I don't understand what you're suggesting/how your idea would work like - maybe you could elaborate a little bit more, pls? 🙂
For example, this is my test setting: https://github.com/mu88/PodBridge/blob/main/tests/Tests/System/SystemTestsFixture.cs
I spawn both my containerized app (built via .NET SDK Container Building Tools) and Playwright and Wiremock - how would that look with your Dockerfile-based approach?

[HofmeisterAn]

the image reference now lives as a string literal in test source code, which most dependency-update bots (Renovate, Dependabot, …) cannot see or update

The idea is to address exactly this. Define the image in a Dockerfile that Renovate or Dependabot can update, and have the tests read the image value directly from that file. The services can then detect version updates and update the Dockerfile accordingly.

[mu88]

Thanks for the pointer to TestSession.GetImageFromDockerfile/DockerfileParser — I really like the idea (native Renovate dockerfile manager support, zero custom config needed).

Before I migrate my own repos to it, I want to make sure I understand how it's meant to be consumed externally: Testcontainers.Commons has IsPackable=false/IsPublishable=false, and I couldn't find it published as a NuGet package under any name, nor referenced by any of the shipped packages (so it can't be transitively pulled in either).

Is there an intended way to consume this today (source-link, a future package split-out, something else), or would it need to be published/exposed first? If not, I'm happy to just vendor the two small files (with attribution) into my own repos - just didn't want to do that without checking whether there's a "proper" way I'm missing, or whether you'd rather I wait for an official package.

---

This reply was drafted with AI assistance (GitHub Copilot CLI); I've reviewed it before posting.

[HofmeisterAn]

It's an internal helper method, so you'll need to copy it or implement something similar yourself.

[mu88]

Would you be open to embed it into the NuGet package Testcontainers or Testcontainers.Xunit? If yes, I'm happy to take over

[HofmeisterAn]

No, I don't plan to include this helper in the library, as it depends on the user's project configuration and layout.

[mu88]

Not wanted by the maintainer. The recommendation is to adapt this pattern by c&p the necessary bits into the custom project configuration. In my case, I will have to create a small NuGet package to avoid duplicating the necessary code within my 15 apps.

[HofmeisterAn]

I'm not against supporting Dependabot or Renovate OOB if that's somehow possible. I just meant with my comment above that there might already be a working "workaround" and that the helper method we currently use is very specific to this repo setup.