# Pull Go modules through CloudRepo

> Point GOPROXY at a CloudRepo Go proxy or group, put the repository token in .netrc, keep the checksum database on, and keep your own modules private.

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.

> **Early access:** Go proxy and group repositories are in early access. Hosting your own Go modules comes later.

## Before you start

- A Go proxy repository. In the [admin portal](https://admin.cloudrepo.io), 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](/docs/authenticate/repository-tokens.html) shows how to create one. For Go, the `login` is the email address of your CloudRepo account, the one that makes the token, and the `password` is the token itself.
- Go. These steps were tested with Go 1.26.5.

## 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`.

`~/.netrc`

```ini
machine your-org.mycloudrepo.io
login you@example.com
password YOUR_REPOSITORY_TOKEN
```

Then set `GOPROXY` to the repository’s URL, and to nothing else:

**Terminal**

```bash
go env -w GOPROXY=https://your-org.mycloudrepo.io/repositories/your-repo
```

`go 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

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

If your team’s own modules live in your git host, name their prefix in `GOPRIVATE`:

**Terminal**

```bash
go env -w GOPRIVATE=github.com/acme
```

Put 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

**Terminal**

```bash
go mod download
```

`go 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.

**Terminal**

```bash
go get github.com/BurntSushi/toml@v1.6.0
```

`go 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

A Go group puts your Go proxies behind one URL. In the [admin portal](https://admin.cloudrepo.io), 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:

**Terminal**

```bash
go env -w GOPROXY=https://your-org.mycloudrepo.io/repositories/go-group
```

Here 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

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:

**Terminal**

```bash
umask 077
NETRC_DIR="$(mktemp -d)"
trap 'rm -rf "$NETRC_DIR"' EXIT
printf '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-repo
go mod download
```

The 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](/docs/ci/overview.html).

## When the go command answers 401

`401 Unauthorized` means CloudRepo got no credential, or one it refused. Check that:

- `~/.netrc`, or the file `NETRC` names, has a `machine` entry for `your-org.mycloudrepo.io`, with its `login` and `password`.
- The `login` is 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.

---

The page: https://www.cloudrepo.io/docs/consume/go.html
