Pull Go modules through CloudRepo
CloudRepo proxies proxy.golang.org for your Go builds. Set GOPROXY to your repository’s URL. Go still checks every public module against sum.golang.org.
One URL in GOPROXY and one entry in .netrc. Then every module your Go build needs comes through
your organization’s CloudRepo host, and CloudRepo keeps a copy of each file the first time a build asks
for it. The go command still checks every module against Go’s checksum database.
Before you start
Section titled “Before you start”- A Go proxy repository. In the admin portal, create a repository with Go as the Format and Proxy as the Kind. Its upstream is proxy.golang.org, the Go module mirror.
- A repository token that covers it. Repository Tokens shows
how to create one. For Go, the
loginis the email address of your CloudRepo account, the one that makes the token, and thepasswordis the token itself. - Go. These steps were tested with Go 1.26.5.
Point Go at the repository
Section titled “Point Go at the repository”The go command sends the credential for your organization’s host from ~/.netrc. The URL carries none, so
go env, which prints GOPROXY, shows no token. Run chmod 600 ~/.netrc so that only you can read the
file. On Windows the file is %USERPROFILE%\_netrc.
machine your-org.mycloudrepo.iologin you@example.compassword YOUR_REPOSITORY_TOKENThen set GOPROXY to the repository’s URL, and to nothing else:
go env -w GOPROXY=https://your-org.mycloudrepo.io/repositories/your-repogo env -w saves the setting in Go’s own settings file, so every shell and every build on this machine uses
it. The URL is https://<organization>.mycloudrepo.io/repositories/<repository>, as the repository’s
Connect page shows.
Do not add ,direct. With ,direct added, Go fetches a module CloudRepo does not have from its source host,
and CloudRepo never sees that pull. Without it, a module CloudRepo cannot serve fails, and you see why.
Leave the checksum database on
Section titled “Leave the checksum database on”Leave GOSUMDB as it is. The go command checks every module it downloads against sum.golang.org, Go’s
checksum database. CloudRepo does not stand in for it: the go command asks sum.golang.org itself. So a module
that came through CloudRepo is checked exactly as one from proxy.golang.org is.
A build whose go.sum already lists a module does not ask about it again. Adding or upgrading a dependency
does. If your network cannot reach sum.golang.org, point GOSUMDB at a mirror of it: set it to
sum.golang.org, a space, and the mirror’s URL. The go command still checks what the mirror returns against
Go’s own key for sum.golang.org, so the check stays on. GOSUMDB=off and a GONOSUMDB pattern turn the check
off. We do not recommend either.
Keep your own modules private
Section titled “Keep your own modules private”If your team’s own modules live in your git host, name their prefix in GOPRIVATE:
go env -w GOPRIVATE=github.com/acmePut your own prefix in place of github.com/acme, and separate several with commas. Modules under it come
straight from your git host, with your git credentials. The go command never asks CloudRepo or
sum.golang.org about them.
Without GOPRIVATE, the go command asks CloudRepo for your private module, CloudRepo asks proxy.golang.org,
and the module’s path reaches Google, as it does with Go’s own defaults. So set it for your own modules, and
only for them: a public module under that prefix skips CloudRepo and the checksum database too.
Pull modules
Section titled “Pull modules”go mod downloadgo mod download fetches every module your go.mod needs. For each module version the go command asks
CloudRepo for three files: its .info, its .mod and its .zip. The first time, CloudRepo fetches each
file from proxy.golang.org, keeps a copy and serves it. After that, it serves the copy.
go get github.com/BurntSushi/toml@v1.6.0go get adds or upgrades a dependency. To pick a version, the go command asks for the module’s version list
or its latest version, which CloudRepo passes through from proxy.golang.org. Then it downloads the version’s
files, as go mod download does, and records the module in go.mod and go.sum.
Use a Go group
Section titled “Use a Go group”A Go group puts your Go proxies behind one URL. In the admin portal, create a repository with Go as the Format and Group as the Kind. Open the group’s settings and choose Manage Group Members: your Go proxies are listed. Turn on Is Member for each one. A group holds at most 10 repositories.
The group asks its members in Priority order and serves the first answer. Only a member that does not have the module passes the request to the next one.
Today every member is a Go proxy of proxy.golang.org, since hosting Go modules comes later. So a group gives your builds one URL that stays the same while you change the proxies behind it.
Point GOPROXY at the group’s URL instead of a repository’s:
go env -w GOPROXY=https://your-org.mycloudrepo.io/repositories/go-groupHere the group is named go-group; put your group’s name in the URL. A group lives on your organization’s
host too, so Go sends it the same ~/.netrc credential. Create the token with the group ticked, and each Go
proxy in it.
In CI, tell the go command where its netrc is with the NETRC environment variable. Store the token as a CI
secret and give it to the step as CLOUDREPO_TOKEN, with the email address of the account that made the token
as CLOUDREPO_USERNAME. The step below writes the netrc in a temporary directory that only the step can read,
and removes it on exit:
umask 077NETRC_DIR="$(mktemp -d)"trap 'rm -rf "$NETRC_DIR"' EXITprintf 'machine your-org.mycloudrepo.io\nlogin %s\npassword %s\n' "$CLOUDREPO_USERNAME" "$CLOUDREPO_TOKEN" > "$NETRC_DIR/netrc"export NETRC="$NETRC_DIR/netrc"export GOPROXY=https://your-org.mycloudrepo.io/repositories/your-repogo mod downloadThe token stays in that file and in the step’s environment, and no command takes it as an argument. The step removes the file when it ends, so a reused runner keeps no copy. For how each CI system keeps a secret, see CI/CD.
When the go command answers 401
Section titled “When the go command answers 401”401 Unauthorized means CloudRepo got no credential, or one it refused. Check that:
~/.netrc, or the fileNETRCnames, has amachineentry foryour-org.mycloudrepo.io, with itsloginandpassword.- The
loginis the email address of the CloudRepo account that made the token. - The token covers the repository, or for a group, the group and each Go proxy in it, and has not expired or been revoked.