go work: Usage, Options & Common CI Errors

Develop across multiple Go modules at once.

go work (Go 1.18+) defines a workspace of several local modules in a go.work file, so the go command resolves their packages from disk instead of published versions - handy for coordinated changes.

What it does

go work init creates go.work; go work use adds module directories to it. With a go.work present, builds use the listed local modules, overriding require/replace resolution for those paths.

Common usage

Terminal

go work init ./api ./worker       # create go.work with two modules
go work use ./shared              # add another module
go work sync                      # sync workspace build list to modules
go work edit -go=1.22             # set the workspace go version

Common CI error: committed go.work breaks the build

CI fails because a committed go.work references local module paths that do not exist on the runner, or it masks a real go.mod problem the release build needs to catch. Fix: usually do not commit go.work (gitignore it); if a build must ignore it, set GOWORK=off or run with go build -mod=mod.

Subcommands

Command	Effect
go work init	Create go.work
go work use <dir>	Add a module dir
go work sync	Sync build list into modules
go work edit	Programmatically edit go.work