packageurls
← Blog

2026-09-02

Adopt a Go vanity path before moving your forge

This is an illustrative example, not a customer report.

It describes the work required to adopt a vanity module path and the separate work required to move its git repository later. It does not establish a migration duration or a customer outcome.

First adopt the vanity module path

Suppose a module currently declares module github.com/acme/payments and its consumers import github.com/acme/payments/client. Creating a DNS record does not change either path. The Go tool treats the module path as the module’s canonical name, as described in the Go module reference.

Choose a hostname you control, such as go.example.com, and configure its Package URLs route to the current forge root, https://github.com. Prove DNS ownership with the provided TXT record, configure the CNAME, and wait for the certificate to become active. Then change the module declaration:

module go.example.com/acme/payments

Update imports of that module’s packages within its own repository, including tests and examples:

import "go.example.com/acme/payments/client"

Publish a release with the new module path. Preserve a required /v2 or later major-version suffix when your module already has one. Downstream consumers must update their imports and go.mod requirements to the vanity path, then run their normal module and test commands. For example, after a compatible release exists at the vanity path:

go get go.example.com/acme/payments@v1.2.0
go mod tidy
go test ./...

Review the resulting go.mod and go.sum changes. A module-path change is not an invisible migration, and adding a hostname cannot rewrite existing consumers automatically. Private modules also need their usual GOPRIVATE configuration and forge credentials.

Later move the forge

Once consumers use go.example.com/acme/payments, a later forge move can retain that vanity path. Copy the repository, tags, and required history to the new forge at the same acme/payments owner/repository path. Keep the module declaration and package imports on the vanity hostname. Update the route’s forge root, for example from https://github.com to https://gitlab.com. The first two path segments must still identify the repository; nested GitLab groups are unsupported.

Test resolution and installation from a clean environment using the released versions consumers need. Verify private access separately with the new forge’s credentials. An HTTP metadata response proves resolution, not that a clone, build, or consumer test succeeded. Do not assume byte-for-byte module or checksum equivalence without checking the release artifacts and history.

Consumers already using the vanity path can keep those import paths during this later move. Consumers still using github.com paths have not adopted the vanity path and need the initial changes described above.

Try it with your own repository

Start free with Go, review the Go dependency example, or read the setup guide. For several modules, repeat the module and consumer changes for each one. One hostname route can cover every supported owner/repo path beneath it.