goproxy-mirror / module pull-through cache

This host proxies and caches modules from proxy.golang.org. Point GOPROXY here to speed up go build/go mod download and cut outbound traffic. Replace mirror.example.com below with this server's actual hostname.

01 — GLOBAL GOPROXY

Set it once for your user

Write the mirror into your Go environment config (go env -w persists it to $GOENV, usually ~/.config/go/env).

shell

go env -w GOPROXY=https://mirror.example.com,direct

# confirm it took
go env GOPROXY

The ,direct fallback means if a module isn't on the mirror, go falls back to fetching straight from the module's VCS host instead of failing.

02 — PER-PROJECT OVERRIDE

Environment variable, scoped to a shell/project

Skip the global write and just export it wherever you want it to apply — a project .envrc (direnv), a Makefile, or a shell profile.

.envrc

export GOPROXY=https://mirror.example.com,direct
export GOSUMDB=sum.golang.org

Unlike npm's .npmrc, Go has no per-repo config file for this — GOPROXY is always an environment variable, so "per-project" means scoping the shell environment, not a committed file.

03 — PRIVATE / INTERNAL MODULES

Bypass the mirror and checksum DB for internal repos

shell

go env -w GOPRIVATE=git.yourcompany.com/*,github.com/your-org/*

Modules matching these patterns skip the proxy and the checksum database entirely, fetching directly via VCS auth instead.

shell

go env -w GONOSUMCHECK=1
go env -w GOFLAGS=-insecure

Prefer GOPRIVATE over this — it's the modern, scoped way to exclude specific module paths.

04 — CI/CD

Environment variables in the pipeline

No repo changes needed — set these in your pipeline's environment.

shell

export GOPROXY=https://mirror.example.com,direct
export GOSUMDB=sum.golang.org
export GOPRIVATE=git.yourcompany.com/*

05 — VERIFY

Confirm builds are going through the mirror

shell

go env GOPROXY
curl -s https://mirror.example.com/github.com/gin-gonic/gin/@v/list

# download something and time it
time go mod download github.com/gin-gonic/gin

Check	Expected result
`go env GOPROXY`	Prints `https://mirror.example.com,direct`
`GET /<module>/@v/list`	`200` with a list of versions — mirror is reachable
First download of a module	Slower — cache miss, fetched from upstream and stored
Repeat download	Fast — served from local module cache

06 — NOTES

Pull-through, not a full copy. This mirror implements the Go module proxy protocol and caches modules as they're requested — it doesn't proactively sync the entire public module ecosystem. The first request for any given module/version is still fetched from proxy.golang.org (or VCS, on fallback).

Checksum verification against GOSUMDB still happens by default even when pulling through a mirror — that's what guarantees module content hasn't been tampered with. Only disable it (GONOSUMCHECK/GOFLAGS=-insecure) for trusted internal networks. Go doesn't have a separate "publish" step — modules are published by tagging a release in the source repo itself.