Go modules
The hub as a Go proxy, private module paths, publishing a module version
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
gocommand 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,GONOSUMDBandGOAUTH, 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
GOPROXYasks 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.GONOSUMDBkeeps your private module paths out of the public checksum database, so their names are never sent there.GOAUTHtells 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.netrcor 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-fallbackleaves proxy.golang.org out, so every module must come from the hub.--gonames thegoprogram whose settings are changed, ifgoon yourPATHis not the one you mean.--profiledefaults to a login calleddefault. 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 getfrom a hub that needs a login to read fails with401 UnauthorizedandGo module proxy authentication required, even thoughgritpack go doctoris healthy. Gritpack's helper offers its token for the proxy address including its/gopath, 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 doctorwill 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 searchandgritpack infolist native packages and crates, not Go modules. Usego list -m -versions example.com/ada/shoutto see versions.- There is no yank for Go modules on the hub (
gritpack package yankworks on native packages only). Use Go's ownretractdirective in a newer version'sgo.mod. - Go modules have no licence field, so hubs with licence rules refuse them.
What just happened
gritpack setupsetGOPROXY,GONOSUMDBandGOAUTHso thegocommand asks the hub first for your private paths and never stores a token.gritpack publishturned 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 importandgo verifyshowed 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
- C and C++ covers headers, sources and libraries.
- Optional deep dive: Releasing a workspace, for several modules released together.