Docker Hub in China — mirrors and private registries

Does Docker Hub work in China? Not as a dependable CI source. Builds that docker pull official or public Hub images on Mainland China runners fail often enough to break release trains — Hub is slow or unreachable often enough that “sometimes works” is still a pipeline defect. The durable pattern: pull and build where Hub works (or use a maintained China mirror), publish to a private registry your China environments can reach, and pin digests so CI does not depend on live Hub.

Preconditions

Before you rewrite Dockerfiles or buy a mirror SKU, lock these facts. Missing any of them leaves China CI on luck.

Precondition	Why DIY stalls
Inventory of every base and service image Dockerfiles and Helm charts pull	Unknown Hub deps fail at the worst time
Classification of which pulls must happen on Mainland China runners	Only those need an in-country registry strategy
A primary registry path per environment (China cloud mirror, private Harbor/ACR/TCR/CCR, or overseas build + sync)	Multiple informal mirrors become supply-chain and ops debt
Digest-pin culture (or immutable tags + digest verify)	Tags move; China outages last longer
At least one cold-pull proof job on a clean China runner	Green overseas CI hides the problem
Clear split: developer laptop path vs production path	“Works on my Mac” becomes company standard

Fixing Docker pulls does not make your SaaS fast for China users — keep container logistics separate from customer traffic architecture (SaaS performance in China, Website accessible in China). Running workloads in Mainland China may still trigger hosting and filing rules; separate image transport from where the service runs (ICP domain-DNS).

Core path

Step	Action	Why
1. Inventory	List every base and service image your Dockerfiles and Helm charts pull	Unknown Hub deps fail at the worst time
2. Classify	Mark which pulls must happen on Mainland China runners	Only those need in-country registry strategy
3. Choose source	China cloud mirror, private Harbor, or overseas build + sync	One primary path per environment
4. Pin	Digests (or immutable tags + digest verify)	Tags move; China outages last longer
5. Cache	Layer cache / pull-through on the China side	Cut repeated cross-border transfers
6. Prove	Cold pull on a clean China runner in CI	Green overseas CI is insufficient
7. Document	Developer laptop path vs production path	Stops “works on my Mac” chaos

Recommended patterns

A) Overseas build, China deploy — CI outside Mainland China pulls from Docker Hub, builds, pushes to a registry replicated or reachable in China. China clusters only pull from that registry.

B) China build with private registry — Maintain Harbor (or cloud ACR/TCR/CCR equivalents) in Mainland China; sync allowlisted images on a schedule from an overseas mirror job.

C) Vendor mirror as pull-through — Some Mainland China cloud providers offer Docker Hub mirror endpoints. Useful, but still treat as an ops dependency: authenticate, rate-limit, and monitor.

What not to do

• Hard-code docker.io/. pulls on China Kubernetes nodes without a mirror
• Rely on anonymous Hub rate limits for release CI
• Assume :latest survives a week of Hub instability
• Tell every developer to “just use a VPN” as the company standard

Pipeline layouts that stay boring: overseas Hub → private registry → sync to Mainland China registry (China K8s pulls only in-country); pull-through cache on an allowlist with last-known-good digests on upstream failure; or air-gapped-style docker save / ORAS import for regulated environments.

Linked reasoning

Overseas-only CI green → false confidence. Global GitHub-hosted runners hide Hub failures until a China colleague or China staging cluster rebuilds. Without a China cold-pull job, release reliability is unproven.

App image pinned, base still from Hub → deploy-time failure. Teams pin app digests but still pull ubuntu, node, or nginx from Hub at scale-out. Flatten the graph: bake bases into your private registry.

Helm upstream defaults → incident discovery. Third-party charts often default to Docker Hub or GCR/Quay. Override image.repository for China environments before go-live, not during ImagePullBackOff.

Live attestation / multi-arch pulls → new failure modes. Supply-chain features add registry round-trips. Cache those artifacts for China jobs too.

Runtime Hub pulls during autoscaling → loud China outages. Pre-pull or use in-country registries only. Cluster scale-out must not depend on a lucky Hub window.

Public mirror without trust model → supply-chain debt. Prefer registries you control or enterprise agreements; verify checksums/digests. Mirrors and sync jobs are part of your supply chain — keep SBOM/attestations available in the China registry, not only overseas.

Difficulty and blockers

• CI that only runs outside China — Add at least one China pull job for production images.
• Base-image sprawl — Bake bases into the private registry; do not leave Hub as a hidden runtime dep.
• Helm / GitOps defaults — Override chart values for every Mainland China environment; use imagePullSecrets consistently; prefer digest pins in production manifests; alert on ImagePullBackOff with registry host labels.
• Rate limits and credentials — Anonymous Hub dies under CI parallelism. Authenticate and cache overseas jobs that still need Hub. If a China job still needs Hub, the migration is unfinished.
• Developer experience drift — Ship an internal “Mainland China laptop pull” doc; rewrite known Hub images to your mirror in renovate/registry.json; fail CI on new unallowlisted registry hosts; teach digests in onboarding.
• Conflating registry access with product access — Container logistics ≠ customer traffic architecture.
• Leadership framing — Fund registry and sync as release reliability (“China environments cannot pull base images during Hub or cross-border incidents”), not as developer inconvenience.

Sample policy shape: production and staging clusters in Mainland China may pull only from company-approved registries; Docker Hub is not an approved runtime source; new bases sync through the pipeline and pin by digest before China use; exceptions need platform on-call approval and an expiry date.

Incident shape when Hub or mirror fails: freeze deploys that need new pulls → confirm cached layers on nodes → fail over to secondary registry if configured → communicate ETA to China feature teams → postmortem which image was not pinned or cached. Goal: schedule slips, not scrambled VPN tutorials in Slack.

China landing partner

Most product teams need a China landing partner (or equivalent in-country platform ops) to stand up Mainland China registries, sync jobs, and cold-pull proof — not another longer “try these mirrors” list. Your team still owns image allowlists and digest policy; the partner path makes China-side registry rails and provider consoles executable when those ops are not already in-house.

What we can offer?

Docker Hub is unreliable from Mainland China networks. Chinaready helps you redesign CI/CD so China runners never depend on a lucky Hub window — mirrors or private in-country registries, digest pins, and proven cold pulls:

1. China Readiness Assessment — Inventory which images must pull on Mainland China runners, choose overseas-build-then-sync versus in-country registry patterns, and mark Hub as a release risk before the next outage.
2. China Access Acceleration — Keep China build/deploy paths and sync/mirror health operable so pipelines fail on application code, not cross-border registry luck.
3. China Product Hosting — Place private registries and workloads that must run in Mainland China on in-country infrastructure with an operable pull path.
4. Mobile App Distribution — Keep mobile build and backend image pipelines on the same digest-pinned, China-reachable registry story so app releases do not invent a second Hub dependency.

Contact us when China CI is blocked on registry access rather than on application code.