Docs menu
Package managers
How Go modules work on Primcloud: go.mod / go.sum, vendoring, private modules, GOPROXY, and lockfile behavior.
On this page
Go apps use modules: dependencies are declared in go.mod, their hashes recorded in go.sum, and they're either downloaded during the build or read from a vendor/ directory you commit. The older dep, godep, govendor, and glide aren't supported.
Install behavior#
The build reads two files:
go.mod: declares required modules and their minimum versions.go.sum: records cryptographic hashes for every module version resolved into the build. Commit it; the Go toolchain verifies every downloaded module against these hashes and fails the build on a mismatch.
Two paths, depending on what's in the repo:
With vendor/modules.txt, nothing is downloaded and the copies in vendor/ are used. Generate it with:
go mod vendor
Then commit the whole vendor/ tree.
Without it, modules are downloaded through the Go module proxy (https://proxy.golang.org) unless you set GOPROXY, and reused in later builds.
Private modules and registries#
If your go.mod requires a module hosted outside the public proxy (a private GitHub repo, a corporate module server, a self-hosted Athens instance), tell the Go toolchain where to fetch it and how to authenticate.
Route private paths around the proxy. Add a GOPRIVATE (or GONOPROXY / GONOSUMCHECK) secret with a comma-separated list of module path prefixes:
GOPRIVATE=github.com/mycompany/*,git.example.com: matching modules bypass the public proxy and the public checksum database.
Provide credentials. Embed a token in GOPROXY for a private module proxy, or use a git URL rewrite for private repos.
A working approach for private GitHub modules:
- Create a GitHub personal access token with
reposcope. - Add a
GOPRIVATE=github.com/mycompany/*secret. - Configure git to use the token: a
.netrcwritten during the build, or a git URL rewrite committed to your repo's build config.
For private module proxies (Artifactory, GitLab, Athens), set GOPROXY to the proxy URL with credentials embedded:
GOPROXY=https://user:[email protected],direct
Secrets are available to the build.
Lockfiles#
go.sum is Go's lockfile, with a twist compared to other ecosystems.
Every module in the build graph appears in go.sum with a hash. The toolchain records hashes for both the module's source archive (h1:...) and its go.mod file (/go.mod h1:...), and verifies both on download.
A hash mismatch fails the build. If a module version's contents differ from what go.sum records, the build stops with a checksum mismatch error before compilation begins.
go.sum doesn't pin versions. Unlike npm's package-lock.json or Yarn's yarn.lock, go.sum doesn't force a specific version graph. It verifies the versions you resolved to. The actual resolution comes from go.mod and Go's minimum version selection.
To lock down the exact set of module versions in a build, either:
- Commit
vendor/: the vendored tree is the definitive source of truth, andvendor/modules.txtrecords the exact versions. - Pin exact versions in
go.modviarequiredirectives with specific patch versions.
Commit both go.mod and go.sum. Committing vendor/ is optional.