cacheport

Ecosystem · Go

Go module proxy cache for CI

Cacheport implements the Go module proxy protocol. Set GOPROXY and the go command fetches modules from a regional cache, while go.sum and the checksum database keep verifying every byte.

CP-GOManifest
Upstream
proxy.golang.org, plus direct VCS for private modules
Endpoint
https://acme.cacheport.cc/go
Config
GOPROXY, credentials in .netrc
Checksums
go.sum and sum.golang.org unchanged
List endpoints
Refreshed every 5 minutes
Module zips
Cached forever, immutable

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.

What gets cached
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

shell
go env -w GOPROXY=https://acme.cacheport.cc/go,direct
go env -w GOPRIVATE=github.com/acme-corp/*

Credentials

~/.netrc
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

.github/workflows/ci.yml
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

.gitlab-ci.yml
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.

Questions

Does Cacheport replace sum.golang.org?

No. Checksum verification stays with the go command and the public checksum database.

Can it serve private modules?

Yes, if you add your Git host as an upstream. Otherwise keep them in GOPRIVATE so they are fetched directly.

Does go mod download use the cache?

Yes. Every module fetch by the go command goes through GOPROXY.

Other ecosystems people set up next

Start on the free plan

20 GB of cache, every registry, unlimited users. Upgrade when your pipelines outgrow it.