Go Import Paths Tie Code to GitHub Unless a Custom Domain Intervenes

Go code that imports github.com/you/project cannot leave GitHub without every importer editing their source, developer Iain Cambridge argued in a Sept. 27 post that drew 311 points on Hacker News. His fix is a custom domain that tells the go command where the code actually lives.

Cambridge's own words on the failure: "if you move your git hosting to GitLab then you have to change your code! Otherwise, you'll be fetching the old version." He describes a company that kept GitLab, GitHub and Azure DevOps running at once because switching was too expensive, and paid for all three.

How the go command finds a repository

The Go modules reference describes the mechanism. When the go command needs a module, it sends an HTTP GET to the module path with ?go-get=1 appended. For golang.org/x/net that request goes to https://golang.org/x/net?go-get=1.

The server replies with an HTML page containing one meta tag:

Part of the tag	Meaning	Example from the docs
import-prefix	The module path or a prefix of it	golang.org/x/net
vcs-type	git, svn, hg or bzr	git
repository-url	Where the source lives	https://github.com/golang/net

The full tag reads <meta name="go-import" content="golang.org/x/net git https://github.com/golang/net">. One response may carry several tags, and a prefix can cover many modules in one repository.

Cambridge's recipe

Cambridge uses two pieces. An Nginx rule spots requests with go-get=1 and returns the meta tag. Everyone else, meaning humans in browsers, is redirected to the GitHub page. His examples of the domain pattern are go.iain.rocks, go.uber.org and go.mongodb.org.

Move the repository and only the tag changes: the import path in every downstream go.mod stays the same. He concludes that "every commercial software development team using Go should be using custom domains for namespacing their internal libraries and packages."

What the docs add, and what they do not

The modules reference notes that GOPROXY decides whether the go command asks a module proxy such as proxy.golang.org instead of the repository directly, and that sum.golang.org verifies checksums separately. Cambridge's post does not discuss either, so a team already relying on a proxy should test a repository move against its own proxy configuration before trusting the redirect alone.

The trade-off is that a vanity domain becomes a thing you must keep renewing and serving. Lose the domain and the paths break in the same way GitHub lock-in would have broken them, only now the failure is yours. That risk is small next to renaming imports across a monorepo, but it is not zero.

Renames are a migration of their own

Import paths are one form of identity a project can lose control of. Our piece on the postmarketOS rebrand as Nura is a reminder that a project's name is something maintainers sometimes have to change on their own schedule, and that anything hard-coded to the old name becomes work for downstream users.

The same applies to code that is hosted somewhere its owners do not fully control. Our Paperclip bus-factor piece looks at maintainer concentration in a fast-growing open-source project, which is one reason a repository might have to move.

The check to run first is grep -r "github.com/" go.mod across your internal modules: the count of hosted paths is the size of the migration you would face today.