GOPROXY caching for private modules: avoiding repeated downloads on a low-traffic service

The short answer

Your reading of the fallback behavior is correct, and the boundary you're looking for is this: the Go toolchain itself has no authenticated caching path for private modules. GOPRIVATE + direct fetching is the default intended path. If you want proxy caching for private modules, you must run (or subscribe to) a proxy that implements the Go module proxy protocol, handles authentication itself, and is listed in GOPROXY ahead of direct. The public proxy at proxy.golang.org will never cache your private paths — it returns 404/410 and the toolchain falls through.

1. Is authenticated private caching supported?

Supported by the protocol, not built into the toolchain. The distinction matters:

• The Go command speaks a simple HTTP protocol ($GOPROXY/<module>/@v/<version>.zip, etc.). Any server implementing it can be a proxy, including one that fronts your private Git host.
• Authentication to that proxy is your responsibility — typically TLS client certs, a .netrc entry matched to the proxy host, or network-level controls (VPC allow-listing). The Go tool does not forward your Git credentials to a proxy, and GOPRIVATE only controls which paths bypass the public proxy and checksum database — it does not authenticate anything.
• Self-hosted options (Athens is the common open-source one) or commercial artifact repositories can fetch from your private Git upstream using credentials configured on the server side, then serve cached zips to CI.

A typical configuration:

GOPROXY=https://goproxy.internal.example,https://proxy.golang.org,direct
GOPRIVATE=git.example.com/myteam/*
GONOSUMDB=git.example.com/myteam/*   # implied by GOPRIVATE, shown for clarity

Note that GOPRIVATE paths also skip checksum-database verification, which is what allows a private proxy to serve them without sum.golang.org integration.

2. Invalidation when a tag moves

There is no invalidation contract, because Go treats module versions as immutable. A proxy caches by module@version; once v1.2.3 is cached, the proxy is entitled to serve that zip forever. If you re-tag v1.2.3 to a different commit, proxies and local module caches that already have the old content will keep serving it — and worse, consumers who fetched before and after the move can end up with different code for the same version. The correct workflow is to publish a new version (v1.2.4 or a pseudo-version) rather than move a tag. If a tag move has already happened, the recovery is to have consumers run go clean -modcache and purge the version from the proxy's storage — treat this as an incident, not a routine operation.

3. Verifying the fetch source per build

Run the download with verbose tracing:

go mod download -x git.example.com/myteam/mod

The output shows the URL each module is fetched from — your proxy's host versus a direct VCS fetch. Two caveats: this only shows the source on a cold cache (modules already in $GOMODCACHE aren't re-fetched), so clear the cache or use a fresh CI workspace for a meaningful check; and -x output is verbose, so grep for the module path. If you run your own proxy, its access logs are the more durable signal — they show whether CI actually consulted the cache before any direct fetch occurred.

For your low-traffic case

One honest consideration: a self-hosted proxy is another service to operate. For a handful of private modules and infrequent clean builds, the simpler alternative is caching $GOMODCACHE between CI runs (most CI systems support keyed caches; key on go.sum). That eliminates repeated origin downloads without any new infrastructure. The private proxy earns its keep when you have many CI jobs, many developers, or want a single audited authentication point for module access.