How Go modules caching works
The module proxy protocol is a small set of read-only URLs: version lists, .info, .mod and .zip files. Cacheport caches the zips and mod files permanently, since a published module version never changes, and refreshes version lists every few minutes.
Verification does not depend on the proxy. The go command checks every module against go.sum and, for new modules, against the public checksum database. A cache cannot serve a module that differs from the one everybody else sees.
- Module zips and .mod files
- Cached forever, shared by every repository in the workspace.
- Version lists and @latest
- Refreshed every 5 minutes.
- Checksum database
- Requests to sum.golang.org go direct, as Go intends.
Set it up
Environment
go env -w GOPROXY=https://acme.cacheport.cc/go,direct
go env -w GOPRIVATE=github.com/acme-corp/*Credentials
machine acme.cacheport.cc
login ci
password <your CACHEPORT_TOKEN>The go command reads proxy credentials from .netrc. In CI, write the file from a secret at the start of the job. Modules matching GOPRIVATE skip the proxy and the checksum database.
Use it in CI
Store the token as a secret named CACHEPORT_TOKEN, then pick your provider.
GitHub Actions
jobs:
test:
runs-on: ubuntu-latest
env:
GOPROXY: https://acme.cacheport.cc/go,direct
steps:
- uses: actions/checkout@v4
- run: printf "machine acme.cacheport.cc login ci password %s\n" "${{ secrets.CACHEPORT_TOKEN }}" > ~/.netrc
- uses: actions/setup-go@v5
with:
go-version-file: go.mod
- run: go test ./...More for GitHub Actions: GitHub Actions setup guide.
GitLab CI
test:
image: golang:1.23
variables:
GOPROXY: https://acme.cacheport.cc/go,direct
before_script:
- printf "machine acme.cacheport.cc login ci password %s\n" "$CACHEPORT_TOKEN" > ~/.netrc
script:
- go test ./...More for GitLab CI: GitLab CI setup guide.
Why keep ,direct at the end
The ,direct fallback lets the go command fetch straight from version control when the proxy answers 404 or 410, for example for a module that has never been published to proxy.golang.org. Use ,off instead if you want builds to fail rather than reach the internet.
Troubleshooting
Errors that usually mean the public registry is the bottleneck, and what Cacheport changes about them.