Wildcard Routing

Wildcard routing lets you cover all repositories under a custom domain prefix with a single rule, eliminating the need to register each repo individually.

Prerequisites

• A Pro account (run gvu subscribe to upgrade)
• A custom domain with DNS CNAME already configured
• gvu CLI installed — see Quick Start

Note: Wildcard routes are not available on the default gomod.io domain. They require a custom domain.

Repo wildcard (W1)

Use repo wildcard when you have many repos under the same GitHub organization or path prefix.

Syntax

gvu add '<domain>/<prefix>/*' 'https://<host>/<org>/*.git'

Shell quoting: The * character must be quoted in the shell to prevent glob expansion. Use single quotes ('...') around arguments containing *.

The * in the vanity path matches any single path segment. The * in the repo URL is replaced with the matched segment.

Example

# Cover all repos under go.mycorp.com/dept1/
gvu add 'go.mycorp.com/dept1/*' 'https://github.com/dept1/*.git'

After creating this rule, any go get request under go.mycorp.com/dept1/ is automatically resolved:

import "go.mycorp.com/dept1/auth"    // → github.com/dept1/auth
import "go.mycorp.com/dept1/config"  // → github.com/dept1/config
import "go.mycorp.com/dept1/utils"   // → github.com/dept1/utils

No need to add routes individually — new repos work immediately.

Subdir wildcard (W2)

Use subdir wildcard when your monorepo contains multiple Go modules in subdirectories. Combined with Go 1.25+ subdir support, this auto-resolves all sub-packages.

Syntax

gvu add <domain>/<prefix>/<repo> https://<host>/<org>/<repo>.git '--subdir=*'

The * in --subdir is replaced with the sub-package path segment from the request.

Example

# Cover all sub-packages in a monorepo
gvu add go.mycorp.com/dept1/mono https://github.com/dept1/mono.git '--subdir=*'

After creating this rule:

import "go.mycorp.com/dept1/mono/api"     // → github.com/dept1/mono (subdir: api)
import "go.mycorp.com/dept1/mono/config"  // → github.com/dept1/mono (subdir: config)
import "go.mycorp.com/dept1/mono/worker"  // → github.com/dept1/mono (subdir: worker)

The Go 1.25+ toolchain clones the repo and reads the go.mod from the matched subdirectory.

Priority rules

When multiple rules could match a request, the resolver uses this priority order:

Example: priority in action

Suppose you have these rules:

# Exact route (priority 1)
gvu add go.mycorp.com/dept1/auth https://github.com/dept1/auth-v2.git

# Repo wildcard (priority 3)
gvu add 'go.mycorp.com/dept1/*' 'https://github.com/dept1/*.git'

• go get go.mycorp.com/dept1/auth → resolves to auth-v2 (exact match wins)
• go get go.mycorp.com/dept1/config → resolves to github.com/dept1/config (wildcard match)

Quota and limits

• Each wildcard route counts as 1 route against your Pro quota (50 total)
• Wildcard routes require a custom domain — gomod.io is not supported
• Repo wildcard (W1) and subdir wildcard (W2) are mutually exclusive per route
• Only one * is allowed in the repo URL

Common scenarios

Scenario A: 20+ repos under an organization

Instead of adding each repo individually:

# One rule covers all current and future repos
gvu add 'go.mycorp.com/platform/*' 'https://github.com/mycorp-platform/*.git'

Scenario B: Monorepo with many Go modules

# One rule covers all sub-packages
gvu add go.mycorp.com/infra/core https://github.com/mycorp/core.git '--subdir=*'

Scenario C: Mix exact and wildcard routes

# Wildcard for most repos
gvu add 'go.mycorp.com/team/*' 'https://github.com/myteam/*.git'

# Override specific repos with exact routes (higher priority)
gvu add go.mycorp.com/team/legacy https://gitlab.com/myteam/legacy.git
gvu add go.mycorp.com/team/fork https://github.com/upstream/fork.git

Troubleshooting

go get fails with “repository not found”

The repo matched by the wildcard doesn’t exist on the Git host. Verify the repo URL by replacing * with the actual package name:

# If go get go.mycorp.com/dept1/foo fails, check:
git ls-remote https://github.com/dept1/foo.git

gvu add rejects wildcard route

Common reasons:

Wildcard route works but sub-package doesn’t resolve

Make sure GOPRIVATE includes your custom domain:

go env -w GOPRIVATE=go.mycorp.com

See Wildcard Routing for full details.