Skip to main content

Go Modules

Publish Go modules using Universal Release.

Detection​

Automatically detected when go.mod exists.

Configuration​

ecosystems:
  go:
    enabled: true
    validation:
      build: true
      test: true
      lint: true

How Go Publishing Works​

Go modules are published via Git tags, not to a central registry:

  1. Tag your commit with semantic version
  2. Push tag to Git repository
  3. Go proxy (pkg.go.dev) discovers it automatically

Publishing​

# Create and push Git tag
release publish --ecosystem go

This:

  1. Validates the module
  2. Creates a Git tag (e.g., v1.2.3)
  3. Pushes tag to remote
  4. Notifies pkg.go.dev

Validation​

Universal Release validates:

  • ✅ go.mod exists and is valid
  • ✅ Build succeeds (go build)
  • ✅ Tests pass (go test ./...)
  • ✅ Linting passes (golangci-lint run)
  • ✅ Module path is valid

Versioning​

Go uses semantic versioning with v prefix:

# Create v1.2.3 tag
release version --bump minor
release publish --ecosystem go

Major Version Updates​

Go requires major version in import path:

// v1
module github.com/user/repo

// v2+
module github.com/user/repo/v2

Update go.mod for major versions:

# Update to v2
echo "module github.com/user/repo/v2" > go.mod

# Publish
release version --set 2.0.0
release publish --ecosystem go

Rollback​

Go doesn't support rollback. Bad versions remain but users can pin to good versions:

require github.com/user/repo v1.2.2 // pin to working version

Best Practices​

Module Structure​

mymodule/
├── go.mod
├── go.sum
├── pkg/
│   └── api/
│       └── api.go
├── internal/
│   └── utils/
│       └── utils.go
└── cmd/
    └── myapp/
        └── main.go

Configure go.mod​

module github.com/user/mymodule

go 1.21

require (
    github.com/some/dependency v1.2.3
)

Use Semantic Import Versioning​

// Import v1
import "github.com/user/repo/pkg/api"

// Import v2
import "github.com/user/repo/v2/pkg/api"

Validation​

Enable comprehensive validation:

ecosystems:
  go:
    validation:
      build: true
      test: true
      lint: true
      vet: true
      staticcheck: true

Proxy Integration​

After pushing tags, pkg.go.dev automatically discovers your module. You can trigger indexing:

# After publishing
curl "https://proxy.golang.org/github.com/user/repo/@v/v1.2.3.info"

Next Steps​