go build -tags: Build Constraints in CI
go build -tags <list> enables build tags so files marked with a matching //go:build constraint are included; files whose constraints are not satisfied are skipped.
Build tags gate integration tests, platform code, or optional features behind a flag. The common CI mistake is a stale // +build syntax or a missing tag that excludes every file.
What it does
go build -tags accepts a comma-separated list of build tags. A file is compiled only if its //go:build expression evaluates true given the active tags, GOOS, and GOARCH. The modern directive is //go:build foo (the old // +build foo form still works but is deprecated).
Common usage
go build -tags=integration ./...
go test -tags="integration e2e" ./...
go build -tags netgo,osusergo -o app ./cmd/appFlags
| Item | What it does |
|---|---|
| -tags=a,b | Enable build tags a and b (comma-separated) |
| //go:build a && b | File compiles only when both tags are set |
| //go:build linux | Implicit GOOS tag; no -tags needed |
| -tags "a b" | Space-separated list also accepted (quote it) |
In CI
Keep an integration tag on slow tests and run them in a dedicated job: go test -tags=integration ./.... The build/module caches still apply; tagged and untagged builds share GOCACHE keyed on the inputs. Ensure the //go:build line is the first line of comments and is followed by a blank line, or the constraint is ignored.
Common errors in CI
"build constraints exclude all Go files in ..." means no file satisfied the active tags (often a missing -tags value or wrong GOOS). "//go:build comment without // +build comment" or "build comment must appear before package clause and be followed by a blank line" flags a misplaced constraint. A test that "passes" because zero files matched is the silent failure -tags causes most often.