Go modules

The hub as a Go proxy, private module paths, publishing a module version

Chapter 12 of 34Current for Gritpack 1.2.63Source: docs/guide/12-go-modules.md

You write Go, some of your modules are private, and you want go get, go.mod and go.sum to keep working as they do. Go already knows how to fetch modules from a proxy, and a Gritpack hub is one: this chapter tells the go command to ask the hub first for your private module paths, and shows how to publish a module version so it can never change afterwards.

Maturity: Experimental. The hub serves the standard Go module proxy protocol, and publishing, setup and diagnosis work. Read the known problem in section 4 before you rely on it for a hub that needs a login to read.

What you will be able to do

  • point the go command at the hub for your private module paths, with proxy.golang.org still used for everything else;
  • check that Go, its settings and your login agree;
  • publish a module version, with the version and publication time stated explicitly so the result is reproducible;
  • make and check a module package file by hand, when you need to.

You need a login on the hub first (Logging in).

What does not change

The go command still resolves, downloads, builds and tests; go.mod and go.sum keep their meaning. The hub never runs go build. It stores each module version exactly as the module proxy protocol describes it: the .info, .mod and .zip files, and the version list.

From Go. This is GOPROXY, GONOSUMDB and GOAUTH, set the way you would set them by hand for any private proxy. Gritpack writes them for you and supplies the credential.

1. Point Go at the hub

In a module directory, run:

$ gritpack setup
setup adapter=go profile=work status=changed proxy=https://packages.example.com:7446/go private=example.com/ada/shout

Unlike Cargo and npm, Go keeps its settings per user, not per project, so this changes your go command's saved settings (go env -w). Three of them:

GOPROXY=https://packages.example.com:7446/go,https://proxy.golang.org
GONOSUMDB=example.com/ada/shout
GOAUTH=/home/you/.frogfish/gritpack/bin/gritpack go-auth --url https://packages.example.com:7446/go --profile work --config /home/you/.frogfish/gritpack/config.toml;netrc
  • GOPROXY asks the hub first. The comma means Go goes on to proxy.golang.org only when the hub answers that a module does not exist. If the hub fails, is unreachable or refuses you, Go stops; it does not quietly fetch a public module of the same name instead.
  • GONOSUMDB keeps your private module paths out of the public checksum database, so their names are never sent there.
  • GOAUTH tells Go to ask Gritpack for a credential when the hub wants one. Gritpack makes a short-lived token from your login each time. No token is stored in .netrc or anywhere else.

By default setup treats only the current module's path as private. Usually you want a whole prefix, such as everything under example.com/ada. Say so with gritpack go setup:

$ gritpack go setup --proxy https://packages.example.com:7446/go --private-prefix example.com/ada --profile work
configured Go proxy https://packages.example.com:7446/go private_prefix=example.com/ada GOAUTH=...

Running it again reports verified instead of configured.

  • --no-public-fallback leaves proxy.golang.org out, so every module must come from the hub.
  • --go names the go program whose settings are changed, if go on your PATH is not the one you mean.
  • --profile defaults to a login called default. If your login has another name, pass it, as above.

Go needs to trust the hub's certificate too. With a certificate from a public authority there is nothing to do. With a private certificate authority, install it in your system's trust store; on Linux you can also point SSL_CERT_FILE at it for the go command.

2. Check it

$ gritpack go doctor --proxy https://packages.example.com:7446/go --private-prefix example.com/ada --profile work
healthy Go proxy https://packages.example.com:7446/go private_prefix=example.com/ada go=go1.24.13 token_expires_at=1794900897

It checks the go command and its version, that GOPROXY, GONOSUMDB and GOAUTH say what they should, that your login can make a token, and that the hub's proxy answers. Go 1.24 or later is needed for GOAUTH.

3. Publish a module version

A Go module version is made of its go.mod, its source files and two facts: the version, and the time it was published. Gritpack asks you for both instead of taking the time from the clock, so running the same command again later produces exactly the same bytes.

Every new version needs a README of at least 100 words and a licence. A Go module has no licence field: put a LICENSE (or LICENCE or COPYING) file at the top of the module, and a README.md beside it.

$ gritpack publish --version v0.1.0 --published-at 2026-11-17T00:00:00Z --dry-run
publication plan=sha256:802fce07... result=RequiresRemoteVerification nodes=1 edges=0 output=./.gritpack/publication-plan.json
go:example.com/ada/shout@v0.1.0 adapter=Go status=Indeterminate ...
...
  check=PUBLICATION_DOCUMENTATION_POLICY status=Passed — README and licence meet the hub's documentation policy
  check=PUBLICATION_LICENSE_DECLARED status=Unverified — no SPDX licence expression
publication verification plan=sha256:802fce07... repository=550e8400-e29b-41d4-a716-446655440000 result=Publishable
  go:example.com/ada/shout@v0.1.0: New
dry run complete; registry was not mutated

The version has its leading v; the time is in RFC 3339 form. Without them, Gritpack stops: invalid workspace: Go member . requires an explicit version.

Unverified — no SPDX licence expression is expected for Go: the LICENSE file satisfies the documentation rule, but there is no machine-readable licence expression. That matters on hubs with licence rules: a rule needs an expression, so a Go module cannot be published under one (README and licence).

Publish:

$ gritpack publish --version v0.1.0 --published-at 2026-11-17T00:00:00Z
...
  go:example.com/ada/shout@v0.1.0: New storage_id=go-sha256:02184d60... digest=sha256:02184d60...

(On a terminal it asks first; in scripts add --yes.) Run the same command again and nothing new is published; Gritpack finds the finished publication:

$ gritpack publish --version v0.1.0 --published-at 2026-11-17T00:00:00Z --yes
publication transaction 01a1e869-ac65-7382-b796-dae5735e6f18 is already Committed; finishing its commit
...

The first account to publish a module path owns it. Another account trying to publish a version of example.com/ada/shout is stopped at the dry run with PUBLICATION_AUTHORITY_DENIED: publisher does not own the Go module path.

A repository with several Go modules releases them together from a workspace, each member with its own version and publication time in gritpack-workspace.toml; see Releasing a workspace.

4. Use a private module

From another module, with the settings from section 1:

go get example.com/ada/shout@v0.1.0

Go asks the hub, the hub asks for a credential, Go runs the GOAUTH command, and the download continues with a token. go.sum records the module's hashes as usual.

Careful: known problem in Gritpack 1.2.63. With Go 1.24 (we tested 1.24.13), go get from a hub that needs a login to read fails with 401 Unauthorized and Go module proxy authentication required, even though gritpack go doctor is healthy. Gritpack's helper offers its token for the proxy address including its /go path, and Go 1.24 matches a token only to a whole host or to the exact address it requested, so it never sends it. A hub that lets anyone read is not affected. Until this is fixed, tell your hub's administrator; gritpack go doctor will not show the problem.

5. Package files by hand

gritpack publish does all of this for you. When you need the steps separately, for example to build the package file on one machine and publish it from another, there are three commands.

Make a package file from a module's source, without building it:

$ gritpack go pack --version v0.1.1 --published-at 2026-11-18T00:00:00Z --output ../shout-v0.1.1.gpk
packed Go module example.com/ada/shout v0.1.1 dependencies=0 ...

Or make one from the three files a Go module proxy serves for a version, for example ones taken from your module cache:

$ gritpack go import --module example.com/ada/shout --version v0.1.0 --info v0.1.0.info --mod v0.1.0.mod --zip v0.1.0.zip --output imported.gpk
packed Go module example.com/ada/shout v0.1.0 dependencies=0 ...

Check one without publishing it:

$ gritpack go verify ../shout-v0.1.1.gpk
verified Go module example.com/ada/shout v0.1.1 dependencies=0 ...

gritpack go publish FILE sends a package file to the hub directly. A hub that keeps signed evidence for every publication refuses that route:

$ gritpack go publish ../shout-v0.1.1.gpk
the hub answered HTTP 409: repository evidence policy requires the publication transaction API

On such a hub, publish from the module directory with gritpack publish, which uses a transaction and leaves a receipt.

What Go modules do not do on a hub yet

  • gritpack search and gritpack info list native packages and crates, not Go modules. Use go list -m -versions example.com/ada/shout to see versions.
  • There is no yank for Go modules on the hub (gritpack package yank works on native packages only). Use Go's own retract directive in a newer version's go.mod.
  • Go modules have no licence field, so hubs with licence rules refuse them.

What just happened

  • gritpack setup set GOPROXY, GONOSUMDB and GOAUTH so the go command asks the hub first for your private paths and never stores a token.
  • gritpack publish turned a module directory, a version and a time into an immutable module version on the hub, and doing it again changed nothing.
  • go pack, go import and go verify showed the same step in pieces.

You can stop here

A Go team that publishes private modules is done, with the known problem in section 4 in mind for hubs that need a login to read.

Next