How do you point a large Testcontainers suite at an internal image mirror when CI blocks Docker Hub?

## Why not fix it at the call sites Wrapping every construction in a compatibility declaration pointed at the mirror works and is unmaintainable at scale. It touches every test module, it must be repeated by every new test, and it hard-codes an infrastructure decision into application test code. When the mirror's address changes you do the migration again. Treat registry location as environment configuration, not as test source. ## The central hook `ImageNameSubstitutor` is Testcontainers' interception point: an implementation with an `apply(DockerImageName)` method plus a description, registered either through the `image.substitutor` entry in `~/.testcontainers.properties` or discovered via the JVM service loader. Every image name the library is asked for passes through it. One implementation, shipped in a shared test-support artefact, can rewrite everything to the internal registry while tests continue to name upstream images. The subtlety is compatibility. Module containers assert on the repository name, so a substitutor that simply returns a differently-named image will break every module container. Return a name declared as a compatible substitute for the original repository so those assertions still pass. ## The no-code option If the mirror is a pull-through cache of Docker Hub that preserves image paths, configure the Docker Hub prefix (`hub.image.name.prefix`, also available as an environment variable) and Testcontainers prepends it to Docker Hub images. No implementation, no shared artefact, and it composes with per-developer configuration. Prefer it when it fits; reach for a substitutor when the mapping is not a uniform prefix — different registries per image family, renamed hardened builds, an allowlist with exceptions. ## Do not forget Testcontainers' own images The library starts helper containers, most importantly the Ryuk reaper that cleans up a session's resources. Those images are pulled like any other, so an environment with no Docker Hub access fails before your first container starts, with an error about an image nobody in your test code named. Mirror them, and override their names through the same configuration file. Disabling the reaper is the other lever, but it moves cleanup responsibility onto the environment and should be a deliberate decision for that environment, not a workaround for a missing mirror. ## Governance, which is the actual principal-level content The mechanism is an afternoon; the operating model is the work. - **Ownership.** One team owns the mirror and its sync policy. "Ask infrastructure to add an image" needs a turnaround time teams can plan around, or they will route around it. - **Onboarding new images.** Adopting a new Testcontainers module pulls a new image. Decide whether the mirror syncs an allowlist (safe, adds friction) or proxies on demand (frictionless, weaker control), and make the failure mode legible: a clear "not in the mirror" error beats a registry timeout. - **Pinning.** Pin tags, ideally digests, in one shared place so every suite resolves the same bytes and an upstream republish cannot change test behaviour silently. - **Local parity.** Developers with Docker Hub access will not notice mirror gaps until CI does. Either apply the same substitution locally or accept that CI is the first place a missing image shows up, and make that error obvious. - **Blast radius.** A single substitutor in shared code affects every suite in the organisation. It needs the same review, versioning and rollout discipline as production configuration; a bad release breaks every build at once. ## Interview framing The mechanism alone is a middle-level answer. What distinguishes a principal answer is treating the mirror as a build dependency with an owner, a sync policy, pinning, a legible failure mode and a change process — and noticing that the helper images are part of the dependency too.