Go Extension

The @putnami/go extension provides build, test, lint, and serve jobs for Go projects in a Putnami workspace. It is fully self-contained — Go and lint tools are downloaded automatically on first use.

Scope: All jobs are project-only — they require a project context.

External tools

• Go (auto-managed, see below)
• golangci-lint
• staticcheck

Enable the extension

putnami deps add @putnami/go

The extension is auto-discovered from workspace dependencies.

Go version management

The extension resolves the Go toolchain automatically:

1. System PATH: if Go is already installed, it is used directly.
2. Managed download: if no system Go is found, reads the go directive from the workspace go.work file and downloads it to .putnami/extensions/@putnami-go/libs/go-{version}/.
3. Fallback: if no go.work exists and no system Go is found, fetches the latest stable version from go.dev.

GOCACHE and GOMODCACHE are shared under .putnami/extensions/@putnami-go/cache/ so compiled packages are reused across all Go projects.

Downloaded toolchains are stored in .putnami/extensions/@putnami-go/ (add to .gitignore).

Jobs

build

Compile Go packages and binaries with cross-compilation support.

• Optionally refreshes dependencies (go.mod and package.json sync) unless --skip-deps
• Writes output to the job output directory (or --output)

Options:

• --target / -t <os/arch> (e.g., linux/amd64)
• --output / -o <path>
• --skip-deps
• --readonly, --mod <readonly|vendor|mod>
• --ldflags, --gcflags, --asmflags, --tags
• --race, --trimpath, --buildmode, --cgo

putnami build . --target linux/amd64

test

Run Go tests with JSON output and optional coverage.

• Detects Go projects via go.mod
• Runs go test -json and parses structured output
• Can generate coverage profile and HTML report

Options:

• --coverage (also generates HTML)
• --race
• --timeout <duration>
• --run <pattern>, --count <n>, --shuffle
• --bench <pattern>, --benchtime <duration>
• --parallel <n>, --failfast
• --coverprofile <file>, --covermode <set|count|atomic>

putnami test . --coverage

lint

Run golangci-lint and/or staticcheck.

• Defaults to --tool all (runs both)
• golangci-lint supports --fix and config discovery

Options:

• --tool <golangci-lint|staticcheck|all>
• --fix (golangci-lint only, default: true)
• --config <path>
• --new, --out-format <format>, --sort-results, --timeout <duration>

Config resolution (golangci-lint):

1. --config flag
2. Project .golangci.yml / .golangci.yaml
3. Workspace .golangci.yml / .golangci.yaml
4. Default config from @putnami/go

putnami lint . --tool golangci-lint

serve

Run Go applications as servers.

• Development mode (default): go run . with file watching and restart
• Production mode (NODE_ENV=production or --watch false): runs the built binary

Options:

• --watch <boolean> (default: true)
• --port <number> (sets PORT env)
• --killPort
• --args <string>

putnami serve . --port 8080

Docker

When the docker publish channel is enabled, the Go extension generates a Dockerfile using gcr.io/distroless/static:nonroot as the base image and copies the statically-linked binary.

Enable in project config:

{
  "publish": ["docker"]
}

Options: --docker-registry <registry>, --docker-tag <tag>, --platform <platform> (default: linux/amd64), --stable.

putnami publish my-api --docker-registry ghcr.io/myorg

Caching and dependencies

• build depends on ^build, tracks: **/*.go, go.mod, go.sum, go.work, package.json.
• test tracks: **/*.go, go.mod, go.sum, go.work, package.json.
• lint tracks: **/*.go, go.mod, go.work, .golangci.yml, .golangci.yaml, package.json.
• serve depends on build, never cached.

Project templates

Template	Description
go-server	HTTP server with net/http, JSON health endpoint, and tests
go-library	Go library with exported function and tests

putnami projects create my-api --template go-server
putnami projects create my-lib --template go-library

Every template produces a project you can serve or test immediately.