Introduction

Fetching private Go modules requires both Go module configuration and Git authentication setup. Most failures come from missing GOPRIVATE settings or incomplete credential flow to the Git host. A clean setup is straightforward once module path rules and credential method are explicit.

Configure Go for Private Module Paths

Tell Go which module path prefixes are private so it skips the public proxy and checksum database for those paths.

go env -w GOPRIVATE=github.com/your-org/*
go env -w GONOSUMDB=github.com/your-org/*

You can include multiple patterns separated by commas. Keep these settings aligned across developer machines and CI.

Prefer SSH Authentication for Developer Machines

SSH avoids token prompts and is usually the most stable local setup.

ssh-keygen -t ed25519 -C "[email protected]"
ssh-add ~/.ssh/id_ed25519
ssh -T [email protected]

Then configure Git URL rewriting so module fetches use SSH automatically.

git config --global url."[email protected]:".insteadOf "https://github.com/"

After this, go commands that resolve GitHub modules typically reuse SSH credentials.

Use Tokens in CI Environments

CI pipelines often use HTTPS with a token rather than SSH keys. Store token in CI secret manager and inject credential helper settings securely.

git config --global url."https://${GITHUB_TOKEN}:[email protected]/".insteadOf "https://github.com/"
go env -w GOPRIVATE=github.com/your-org/*
go mod download

Never print token values in logs. Ensure shell tracing is disabled for sensitive commands.

Running go get and go mod tidy

With auth and environment configured, fetch private modules normally.

go get github.com/your-org/[email protected]
go mod tidy

In modern Go, module-aware workflows primarily use go get for dependency version updates and go mod commands for graph hygiene.

Troubleshooting Checklist

If fetching still fails, check these quickly:

• go env GOPRIVATE includes the exact module prefix.
• Git can clone the repository directly with the same URL style.
• Module path in go.mod matches repository import path exactly.
• CI has access to the same organization or project scope.

You can also run with verbose Git tracing in a safe environment to identify auth source problems.

GIT_TRACE=1 GIT_CURL_VERBOSE=1 go mod download

Use this only when logs are protected, since traces may contain sensitive metadata.

Team and Security Practices

Standardize one documented setup for local development and one for CI. Mixed ad hoc credential strategies across teams usually cause flaky onboarding and intermittent pipeline failures.

Rotate tokens periodically and scope them to least privilege. For organization-wide automation, prefer short-lived credentials where platform support exists.

In containerized builds, avoid baking credentials into images. Mount secrets at runtime and clear them after module download when possible.

For monorepos with many private modules, prewarming the module cache in CI can reduce build time significantly. Keep cache keys tied to go.sum and Go toolchain version so stale artifacts do not mask dependency updates or produce inconsistent build behavior.

Common Pitfalls

A common pitfall is setting GOPRIVATE too narrowly, for example one repository only, then importing another private module from the same organization. Use prefix patterns that match actual dependency structure.

Another issue is relying on interactive authentication flows in CI. Non-interactive environments need explicit credentials and cannot respond to prompts.

Developers also forget that module path and repository path must match. Even with valid credentials, a path mismatch leads to confusing not found errors.

Finally, teams enable verbose tracing in shared logs and accidentally leak sensitive details. Restrict debugging output and sanitize logs during auth troubleshooting.

Summary

• Set GOPRIVATE and related env vars for private module prefixes.
• Use SSH for local development and token-based auth for CI when appropriate.
• Ensure Git URL style and module import path are consistent.
• Validate setup with direct Git access before blaming Go tooling.
• Apply least-privilege credential and logging hygiene practices.