Go

Provides Go language support for heph. The go provider analyzes Go packages and generates targets for building libraries, binaries, and tests. It reads package metadata, resolves source files and module dependencies, and wires up the targets needed to compile and run Go code. Managed drivers do the underlying work: toolchain provisioning (go_toolchain), package metadata analysis (go_golist), Go package compilation (go_compile), test main generation (go_testmain), and per-package lint/format analysis (go_lint, go_lint_gate, go_lint_fix, go_format, go_format_check).

Driver

A driver is the execution backend that knows how to run a particular kind of target. This plugin registers nine drivers: go_toolchain, go_golist, go_compile, go_testmain, go_lint, go_lint_gate, go_lint_fix, go_format, and go_format_check. These are internal — you should not interact with them directly.

Enabling it

The Go plugin is an external plugin — it is not compiled into the heph binary. It ships as a shared library (cdylib) with a manifest file (heph-go-plugin.json). A single plugins: entry loads the provider and all four drivers at once.

Use url: to have heph fetch and cache the plugin automatically:

channel

.hephconfig
plugins:
  - url: https://github.com/hephbuild/heph-artifacts-v1/releases/latest/download/heph-go-plugin.json
    checksum: sha256:<hex>   # optional; pin from heph-go-plugin.json.sha256

The checksum field is optional but recommended — it pins the manifest to a known digest so a tampered or misdelivered manifest is rejected before loading. See Pinning manifests with checksums for details.

Configuration

channel

.hephconfig
plugins:
  - url: https://github.com/hephbuild/heph-artifacts-v1/releases/latest/download/heph-go-plugin.json
    checksum: sha256:<hex>   # optional
    options:
      gotool: "1.27.0"       # required — pinned version, "host", or a target address
      skip: []               # optional
      checksums:             # optional; recommended for supply-chain verification
        "1.27.0/linux/amd64": "<sha256hex>"
        "1.27.0/darwin/arm64": "<sha256hex>"

Options

Option	Type	Default	Description
`gotool`	`string`	required	Go toolchain to use. Set to a pinned version like `"1.27.0"` to download the SDK hermetically from `go.dev/dl`, `"host"` to use the `go` binary already on the host's `PATH`, or a target address like `"//@heph/bin:go"` to use the toolchain a target produces.
`govet`	`string` (target address)	the plugin's own published `heph-govet` build	The `heph-govet` binary that lint and format targets run. See Pinning the analyzer binary.
`cctool`	`string` (target address)	the host's `cc`, via hostbin (`//@heph/bin:cc`)	The C compiler a race-detector build stages where it needs cgo. Only resolved when such a build actually runs.
`runner`	`string` (target address)	unset	Exec runner every Go tool (`go list`, `go tool compile`/`asm`/`pack`, `gofmt`, `heph-govet`) runs under, or `"local"`. Reaches the `go_*` drivers as their default and this provider's own `bash` targets (the standard library install, the third-party module download) as their `runner` field. See Running Go tools under a runner.
`checksums`	`map[string, string]`	`{}`	Expected SHA-256 digests for hermetic SDK tarballs, keyed `"<version>/<goos>/<goarch>"` (e.g. `"1.27.0/linux/amd64"`), and for `govet` release downloads, keyed `"govet/<tag>/<goos>/<goarch>"`. Look up SDK values at go.dev/dl/?mode=json. When a key is missing the download is unverified (a warning is logged). SDK checksums have no effect when `gotool = "host"`.
`skip`	`string[]`	`[]`	Workspace-relative glob patterns for directories to exclude from Go package discovery.
`walk_db`	path	`<homeDir>/heph-plugin-go-fswalk.db`	Path to the filesystem walk cache database.

Toolchain modes

Hermetic (recommended) — set gotool to a Go version string:

.hephconfig
options:
  gotool: "1.27.0"
  checksums:
    "1.27.0/linux/amd64": "<sha256>"
    "1.27.0/darwin/arm64": "<sha256>"

The plugin downloads the Go SDK tarball for the host platform from go.dev/dl, verifies its SHA-256 (when a checksums entry is present), and caches the extracted SDK. Every build, test, and analysis target depends on that cached SDK and points GOROOT at it. No Go installation is required on the host.

Host — set gotool to "host":

.hephconfig
options:
  gotool: "host"

The plugin uses the go binary found on the host's PATH. Builds are not reproducible across machines with different Go versions.

Target — set gotool to a target address:

.hephconfig
options:
  gotool: "//@heph/bin:go"

The plugin builds the given target and uses its output as the Go toolchain — for example a go binary exposed by the hostbin provider, or a go built by a nix target. The target must produce a single output: either a go binary file, or a directory containing bin/go. Reproducibility depends entirely on what the target produces.

Skipping directories

Use skip to prevent the provider from scanning directories you don't want included in Go package discovery — for example, directories containing non-module code, generated stubs, or vendored packages managed outside of heph. Each pattern is matched against the workspace-relative path of the directory.

channel

.hephconfig
plugins:
  - url: https://github.com/hephbuild/heph-artifacts-v1/releases/latest/download/heph-go-plugin.json
    options:
      gotool: "1.27.0"
      skip:
        - vendor
        - "internal/generated/**"

skip is a hard boundary for first-party packages: it applies to both discovery and direct target resolution. Addressing a first-party package inside a skipped subtree — for example heph run //vendor/pkg:build — returns not found. Standard library (@heph/go/std/…) and third-party module (@heph/go/thirdparty/…) packages live outside the workspace tree and are never affected by skip.

Running Go tools under a runner

Set runner to run every Go tool inside a described environment instead of on the host — see Runners for what a runner is:

.hephconfig
options:
  gotool: "1.27.0"
  runner: "//tools/devenv:runner"

It reaches every Go target — the go_*-driver ones and the plain bash targets this provider also generates (the standard library install, the third-party module download, and the binary/test-binary links) alike. A build where only half moved into the environment mixes toolchains and fails to link.

gotool: "host" composes with it: under a runner, "host" means the go found on the runner's PATH, resolving GOROOT by running go env GOROOT inside that environment. Left unset (no runner), gotool: "host" behaves exactly as before — heph's own PATH. gotool: "<version>" and a target-address gotool are unaffected either way — both already resolve to a staged path inside the sandbox and never probe a host.

A hand-written target using a go_* driver can set its own runner field (including runner = "local" to opt out); there is no per-package override for generated targets — the option is workspace-wide.

Tests are deliberately not covered by it. A build wants the compiler's environment; a test often wants the runtime's — a separate decision. Point a package's tests at a runner with provider_state instead:

BUILD
provider_state(
    provider = "go",
    test = {"runner": "//tools/devenv:runner"},
)

With test.runner unset, a test falls back to the plugin's own runner option, so a workspace that wants everything in one environment sets it there and needs nothing per package. See Test environment for the rest of what test accepts.

Usage

The provider analyzes each Go package from its go.mod and source files and generates targets for it — you don't write target() calls for Go code. For a package it produces:

Target	Builds	Labels
`:build`	The library or, for `package main`, the binary.
`:test`	The package's tests.	`test`, `go-test`

Explore what was generated for the package in the current directory:

terminal
heph query all .

Then build or test by address:

terminal
heph run //cmd/server:build     # compile the binary
heph run //lib/auth:test        # run the package's tests

Race detector

Every package with tests also gets :test_race and :xtest_race — test and xtest, compiled and linked with Go's race detector.

Target	Builds	Labels
`:test_race`	The package's tests, with `-race`.	`test-race`, `go-test-race`
`:xtest_race`	The package's external tests, with `-race`.	`test-race`, `go-test-race`

terminal
heph run //lib/auth:test_race     # run this package's tests under the race detector
heph run 'label(test-race)'       # every race-detector test in the workspace

Race instrumentation covers the whole program, standard library included, so race targets are several times slower to build and run than test/xtest. That's why they carry the test-race/go-test-race labels instead of test/go-test: heph run 'label(test)' keeps meaning the ordinary suite. Run both together with label(test) || label(test-race).

:test_race/:xtest_race accept the same @v=NAME variant selection and the same provider_state(test = {...}) configuration — env, pass_env, pre_run, runner, and so on — as :test/:xtest. See Test environment. On Linux, a race build always links with buildmode = "exe", even if the selected variant declares buildmode = "pie" — Go's race detector doesn't support PIE there. On darwin the variant's declared buildmode is honored as-is.

A race build needs a C compiler everywhere except darwin, where Go's race runtime has no cgo dependency. On Linux, the cctool option picks which C compiler to stage — it defaults to the host's cc, found through the hostbin provider:

.hephconfig
options:
  gotool: "1.27.0"
  cctool: "//@heph/bin:cc"    # default; point elsewhere for a hermetic compiler

cctool is resolved only when a race build that needs cgo actually runs — an ordinary build, and a darwin race build, never touch it.

Linting and formatting

A Go module gets four extra targets the moment it has a .golangci.yml (or .golangci.yaml) at its module root — no provider_state toggle needed. Lint analysis sees the module's whole first-party dependency graph, not just the package being linted, so interprocedural checks (a printf-style wrapper, a context that's never cancelled, …) stay accurate across package boundaries.

Target	Does
`lint-check`	Fails the build if the package has lint findings. Reports only, writes nothing.
`lint`	Applies the linter's suggested fixes back into the package's sources.
`format-check`	Fails the build if any file in the package isn't formatted. Reports only, writes nothing.
`format`	Reformats the package's sources in place.

terminal
heph run //lib/auth:lint-check      # gate: fails on findings
heph run //lib/auth:lint            # fixer: applies suggested fixes
heph run //lib/auth:format-check    # gate: fails if unformatted
heph run //lib/auth:format          # fixer: reformats in place

lint and format rewrite files in the package directory — the same in-place rewrite behavior as any codegen fixer target. A package whose module has no .golangci.yml gets none of these four targets; :build and :test are unaffected either way.

Within a module that does opt in, provider_state(lint = False) drops lint-check/lint for a package while leaving format/format-check in place — the two families are gated independently.

Selecting and configuring linters

linters.default/enable/disable in .golangci.yml select among four available linters:

Linter	Covers
`govet`	The standard `go vet` analyzers, plus opt-in ones (`shadow`, `fieldalignment`, `nilness`, `sortslice`, `unusedwrite`).
`staticcheck`	staticcheck (`SA*`) checks.
`gosimple`	gosimple (`S*`) checks.
`stylecheck`	stylecheck (`ST*`) checks.

.golangci.yml
linters:
  default: standard   # "standard" (govet only, the default), "all", or "none"
  enable:
    - staticcheck
  settings:
    govet:
      enable: [shadow]
      settings:
        printf:
          funcs: [Wrapf]
    staticcheck:
      checks: [all, -ST1000]

Key	Effect
`linters.default`	`standard` (`govet` only — the default), `all` (all four linters), or `none`.
`linters.enable` / `linters.disable`	Add or remove linters from the default set, by name.
`linters.settings.govet.enable` / `.disable` / `.enable-all` / `.disable-all`	Turn individual vet analyzers on or off.
`linters.settings.govet.settings.<analyzer>.<flag>`	Per-analyzer flags, e.g. `printf.funcs`, `shadow.strict`.
`linters.settings.{staticcheck,gosimple,stylecheck}.checks`	Check patterns to include, e.g. `all`, `SA1000`, `-ST1003`, `SA1*`.
`linters.settings.stylecheck.initialisms` / `.dot-import-whitelist` / `.http-status-code-whitelist`	Config consumed by specific stylecheck checks.

note

unused needs whole-program analysis and isn't available in this per-package model.

Suppressing findings

handler.go
func handle() { //nolint:staticcheck
	...
}

//nolint[:linter1,linter2] on its own line covers the next line of code; trailing at the end of a line of code covers that line; bare //nolint (or //nolint:all) covers every linter. Match against staticcheck for any staticcheck/gosimple/stylecheck finding — golangci-lint folds those three into one linter name.

linters.exclusions suppresses by rule instead of by comment:

.golangci.yml
linters:
  exclusions:
    generated: lax        # lax (default) | strict | disable
    presets:
      - common-false-positives
    rules:
      - linters: [staticcheck]
        path: "_test\\.go$"
        text: "S1002"
    paths:
      - "third_party/.*"

Key	Effect
`generated`	Whether findings in generated files are excluded: `lax` (default), `strict`, or `disable`.
`presets`	Built-in exclude patterns: `comments`, `common-false-positives`, `legacy`, `std-error-handling`.
`rules`	Per-rule `linters` / `path` / `path-except` / `text` filters — all present conditions on a rule must match.
`paths` / `paths-except`	Whole-file regexes to exclude (or to exclusively include).

Formatters

format and format-check default to gofmt when .golangci.yml sets no formatters. Enable gofumpt and/or goimports (import sorting only — it does not add missing imports) and tune their settings:

.golangci.yml
formatters:
  enable:
    - gofumpt
    - goimports
  settings:
    gofmt:
      simplify: true
    gofumpt:
      extra-rules: true
    goimports:
      local-prefixes: [github.com/myorg/myrepo]
  exclusions:
    generated: lax
    paths:
      - "_gen\\.go$"

Key	Effect
`formatters.enable`	`gofmt` (default), `gofumpt`, `goimports`. Applied imports → gofmt → gofumpt regardless of listing order.
`formatters.settings.gofmt.simplify` / `.rewrite-rules`	`gofmt -s` simplification and rewrite rules.
`formatters.settings.gofumpt.module-path` / `.extra-rules`	gofumpt options.
`formatters.settings.goimports.local-prefixes`	Import groups treated as "local" when sorting.
`formatters.exclusions.generated` / `.paths`	Same shape as the linter exclusions, applied to formatting instead.

Pinning the analyzer binary

Lint and format targets run through heph-govet, a binary the plugin downloads and verifies automatically the first time it's needed — nothing to configure by default. The default download is itself an HTTP Fetch target, checksum-verified against a digest baked into the plugin at release time.

Point the govet option at a different target address to use another build instead — for example one that compiles heph-govet from a local source tree:

.hephconfig
options:
  gotool: "1.27.0"
  govet: "//tools/heph-govet:build"

Building heph-govet from source needs a Go toolchain of at least the version its own module targets — set gotool accordingly, or the build fails. The plugin's default published binary is unaffected either way.

Add a "govet/<tag>/<goos>/<goarch>" entry to checksums to verify a pinned govet release download other than the plugin's own build.

Provider functions

The go plugin exposes one helper function in every BUILD file under the heph.go namespace.

Function	Signature	Returns
`heph.go.build_addr`	`build_addr(pkg: string, variant: string = "") -> string`	The address of `pkg`'s `build` target, optionally pinned to a named build variant. `pkg` accepts a package path or a path relative to the calling BUILD file's package.

The function enforces its argument types: wrong type, missing required argument, or unknown keyword produces a clear error.

See Build variants for usage details.

Build variants

Go targets compile against a build variant: a named, reusable set of factors — target OS/architecture, build tags, GOEXPERIMENT, extra compiler and linker flags — declared once and selected by name from an address. There is no implicit variant, so declare at least one before building.

Declare variants with provider_state, scoped to a Go module (the directory containing go.mod):

BUILD
provider_state(provider = "go", variants = {
    "base": {"goos": "linux", "goarch": "amd64"},
    "release": {
        "inherit": "base",
        "goexperiment": ["arenas"],
        "gcflags": ["-l"],
        "ldflags": ["-s", "-w"],
        "tags": ["prod"],
    },
})

Field	Type	Required	Meaning
`goos`	`string`	yes (directly or via `inherit`)	Target operating system, e.g. `"linux"`.
`goarch`	`string`	yes (directly or via `inherit`)	Target architecture, e.g. `"amd64"`.
`tags`	`list[string]`	no	Build tags to compile with.
`goexperiment`	`list[string]`	no	`GOEXPERIMENT` values to enable.
`gcflags`	`list[string]`	no	Extra flags passed to `go tool compile`.
`ldflags`	`list[string]`	no	Extra flags passed to `go tool link`.
`buildmode`	`string`	no	Link mode: `"exe"` (default) or `"pie"`. See Buildmode: static vs PIE.
`inherit`	`string`	no	Name of another variant in the same map to start from.

cgo is not a variant field — every heph-built Go target compiles with CGO_ENABLED=0, unconditionally.

inherit resolves the named variant first, then overlays the fields you set on top of it. List fields (tags, goexperiment, gcflags, ldflags) are replaced, not merged — in the example above, release ends with tags = ["prod"], not ["prod", ...] plus whatever base had. goos and goarch can be omitted when inheriting from a variant that already sets them. Inheritance cycles are rejected with an error.

Buildmode: static vs PIE

buildmode controls the binary's link mode for a package main target's :build:

Value	Behavior
`"exe"`	Default. Matches plain `go build`. On Linux, links a statically linked binary with no interpreter — it runs in a `FROM scratch` or distroless image.
`"pie"`	Position-independent executable. On Linux this always needs `/lib/ld-linux-<arch>.so.1` present at run time, even with cgo disabled.

BUILD
provider_state(provider = "go", variants = {
    "release": {"goos": "linux", "goarch": "arm64", "buildmode": "pie"},
})

On darwin/arm64 the Go linker makes every executable PIE regardless of this setting, so both values produce the same kind of binary there — the knob only changes behavior on Linux.

Library targets and archives are unaffected by buildmode; it only applies to the linked binary of a package main.

Selecting a variant

Add @v=NAME to a target address:

terminal
heph run //cmd/server:build@v=release     # compile with the "release" variant
heph run //cmd/server:test@v=base         # run tests under "base"

A variant is resolved by walking from the target's package up to its module root — the closest ancestor package that declares NAME wins. A variants map declared outside the target's module (above its go.mod) doesn't apply to it. An address with no matching @v= fails with the list of variant names available at that point in the tree.

A package main target's :build also accepts the plain address, with no @v= at all, as a shortcut: it forwards to whichever declared ancestor variant's goos/goarch match the machine running the command.

terminal
heph run //cmd/server:build     # forwards to a variant matching this machine, if one exists

If no declared variant matches the host, the plain address doesn't resolve. Library targets have no such shortcut — always give them @v=NAME.

In a BUILD file, don't assemble these address strings by hand — use heph.go.build_addr():

BUILD
heph.go.build_addr(pkg, variant = "")

Argument	Default	Meaning
`pkg`	required	The target's package, e.g. `"cmd/server"`. Starting with `./` or `../`, it resolves relative to the calling BUILD file's package instead — same rules as relative addresses. A path that resolves outside the workspace is an error.
`variant`	`""`	The variant name. Omit (or pass `""`) for the plain, unparameterized address.

cmd/server/BUILD
target(
    name = "image",
    driver = "bash",
    deps = {"bin": heph.go.build_addr("cmd/server", "release")},
    run = "./package-image.sh $SRC_BIN $OUT",
    out = "image.tar",
)

The image target now embeds the release-variant binary. Calling build_addr only formats the address — it does not resolve or build anything, and it does not check that the variant is actually declared.

pkg can also be given relative to the calling package:

cmd/server/BUILD
heph.go.build_addr("./worker", "release")   # -> //cmd/server/worker:build@v=release
heph.go.build_addr("../shared")             # -> //cmd/shared:build

note

List every provider-exposed BUILD function with heph inspect functions.

Generated code and test data

The provider analyzes Go packages, but a package often needs files that aren't hand-written .go sources — generated code (protobuf stubs, mocks, enums) or fixtures a test reads at runtime. You don't wire these into the :build and :test targets by hand. Instead you label the target that produces them and the provider picks it up automatically.

Three labels are recognized:

Label	Attach to a target that produces…	Pulled into
`go_src`	Generated `.go` sources (and small embedded files cheap to produce).	`:build`, `:build_test`
`go_embed_src`	Embed-only assets for `//go:embed` that should not block `query`/`list`.	`:build`, `:build_test`
`go_test_data`	Files a test reads at runtime (fixtures, goldens).	`:test`, `:xtest`

`go_src` — generated source

Label a codegen target go_src and its output tree is unpacked into the package before analysis, so the generated .go (and embedded) files are compiled as part of the package — exactly as if you'd committed them. This is how go list, the build, and the tests all see code produced by protoc, mockgen, stringer, and friends.

api/BUILD
target(
    name = "proto",
    driver = "bash",
    codegen = "copy",
    labels = ["go_src"],
    deps = {"src": glob("*.proto")},
    out = glob("*.pb.go"),
    run = "protoc --go_out=. $SRC_SRC",
)

The api package now builds and tests with api.pb.go included — no deps entry, no reference to :proto anywhere. Add the generator, label it, done:

terminal
heph run //api:build     # compiles your sources + the generated .pb.go
heph run //api:test      # tests see the generated code too

tip

Pair go_src with codegen = "copy" (see Codegen) so the generated files also land in the tree for your editor and gofmt, and heph tool gen-gitignore keeps them out of git.

`go_embed_src` — embed assets excluded from package analysis

Label a target go_embed_src when it produces files referenced by //go:embed that are expensive to build and should not run during query, list, or IDE metadata operations.

Unlike go_src, outputs from go_embed_src targets are not staged during package analysis. heph query, heph list, and editor integrations complete without triggering the asset build. The files are staged only when the package actually compiles.

web/BUILD
target(
    name = "bundle",
    driver = "bash",
    labels = ["go_embed_src"],
    deps = {"src": glob("frontend/**")},
    out = "dist",
    run = "npm ci && npm run build -- --outdir=$OUT",
)

The package's //go:embed dist/* directive is satisfied at compile time, without a frontend build running during query or metadata operations.

go_embed_src respects go_codegen_root: when an ancestor sets go_codegen_root = True, embed-src targets are searched by package prefix across the whole subtree, the same as go_src.

tip

If your embed asset is cheap to produce (a few static templates, a small binary), go_src works fine — its output tree is staged before both analysis and compile. Use go_embed_src specifically when the asset build is expensive enough that blocking query or metadata on it is costly.

`go_test_data` — test fixtures

Tests frequently read files from disk — golden files, sample inputs, a fixture database. Label the target that produces them go_test_data and its outputs are staged into the sandbox next to the test binary when :test (or :xtest) runs, so the test finds them at the path it expects.

parser/BUILD
target(
    name = "fixtures",
    driver = "bash",
    labels = ["go_test_data"],
    deps = {"src": glob("schema/*.json")},
    out = glob("testdata/*.golden"),
    run = "./gen-goldens.sh",
)

terminal
heph run //parser:test     # the .golden files are present in the sandbox

Because the sandbox is isolated, a test only sees the files its package declares. Labeling a fixture target go_test_data is what makes those files visible to the test without loosening isolation — the test stays reproducible and cacheable.

Generated dependency addresses

The provider wires each package's imports automatically through two address families it generates — you reference these only when reading a dependency graph, never by hand:

Address	Resolves to
`@heph/go/std/<pkg>`	A package from the Go standard library.
`@heph/go/thirdparty/<module>@<version>`	A pinned third-party module.

Because the module and version are part of the address, a dependency bump changes the address and invalidates only the targets that import it.

provider_state — per-package configuration

provider_state(provider="go", ...) placed in a BUILD file configures the Go provider for that package. go_codegen_root and go_codegen_deps always extend to descendant packages. test, lint, and link apply to the exact declaring package by default; add recursive = True to extend them to descendants. When the same key applies at multiple depths, the deepest (closest) declaration wins.

tip

heph inspect states //pkg --inherited prints every provider_state declaration a package inherits, root first — a quick way to check what a package actually sees before chasing it through the BUILD file tree. See Inspecting builds.

Recognized keys

Key	Type	Effect
`go_codegen_root`	`bool`	When `True` on an ancestor, `go_src` and `go_embed_src` targets are searched across the whole subtree rooted here instead of only the leaf package. Use when one generator feeds many descendant packages. Always applies to descendants, independent of `recursive`.
`go_codegen_deps`	`list[string]`	Explicit codegen target addresses injected into every descendant package's sandbox. For generators not labelled `go_src`. The closest ancestor carrying it wins. Always applies to descendants, independent of `recursive`.
`go_embed_deps`	`list[string]`	Explicit embed-asset target addresses injected into every descendant package's compile step. The analog of `go_codegen_deps` for the `go_embed_src` lane — for targets that produce embed-only assets but aren't labelled `go_embed_src`. The closest ancestor carrying it wins.
`variants`	`map[string, struct(...)]`	Declares named build variants that this package and its descendants select with `@v=NAME`, bounded to the enclosing Go module.
`test`	`bool \| struct(...)`	Controls test-target generation and configuration. Applies to the exact package by default; add `recursive = True` to extend to descendants. See below.
`lint`	`bool`	`lint = False` drops the package's `lint-check`/`lint` targets; `lint = True` (or unset) keeps them, within a module that opts into linting at all. `format`/`format-check` are unaffected. Applies to the exact package by default; add `recursive = True` to extend to descendants. See Skipping lint.
`link`	`struct(...)`	Link settings for a `main` package's `build` (binary) target. Applies to the exact package by default; add `recursive = True` to extend to descendants. See Link configuration.
`recursive`	`bool`	When `True`, extends this state's `test`, `lint`, and `link` config to all descendant packages. `go_codegen_root` and `go_codegen_deps` are unaffected — they always apply to descendants.

Skipping tests

test = False disables test-target generation for the exact declaring package. Add recursive = True to disable across the whole subtree. A deeper test = True (or the struct form) re-enables them — the closest applicable ancestor wins.

BUILD
# Disable tests for this package only:
provider_state(provider = "go", test = False)

# Disable tests for this package and all descendants:
provider_state(provider = "go", recursive = True, test = False)

# Re-enable in a subdirectory:
provider_state(provider = "go", test = True)

Skipping lint

lint = False drops the lint-check/lint targets for the exact declaring package, the same scoping rules as test: add recursive = True to disable across the whole subtree, and a deeper lint = True re-enables them — the closest applicable ancestor wins. This only applies within a module that already has a .golangci.yml/.golangci.yaml at its root; it can't turn linting on for a module that hasn't opted in.

BUILD
# Drop lint targets for this package only:
provider_state(provider = "go", lint = False)

# Drop lint targets for this package and all descendants:
provider_state(provider = "go", recursive = True, lint = False)

# Re-enable in a subdirectory:
provider_state(provider = "go", lint = True)

format/format-check are a separate family and keep running regardless — they're a different tool with a different verdict. The internal per-variant lint-analysis unit also stays resolvable even when a package opts out, so a still-linted importer can still pull in this package's facts for interprocedural analysis; it produces no user-visible diagnostics on its own.

Test environment

The struct form configures the generated test/xtest run targets. Like the boolean form, it applies to the exact declaring package by default. Add recursive = True to extend it to descendants. A struct-form state also re-enables tests even when an ancestor set test = False.

BUILD
provider_state(
    provider = "go",
    test = {
        "env":              {"FOO": "1"},   # hashed; affects the cache key
        "pass_env":         ["HOME"],       # hashed; affects the cache key
        "runtime_env":      {"BAR": "2"},   # not hashed; runtime-only
        "runtime_pass_env": ["PATH"],       # not hashed; runtime-only
        "pre_run":          ["export FOO=bar", "mkdir -p ./scratch"],
        "runner":           "//tools/devenv:runner",   # hashed; affects the cache key
    },
)

Field	Type	Hashed	Description
`env`	`map[string]`	yes	Env vars set on the test run.
`pass_env`	`list[string]`	yes	Names of host env vars forwarded to the test run.
`runtime_env`	`map[string]`	no	Like `env` but excluded from the cache key.
`runtime_pass_env`	`list[string]`	no	Like `pass_env` but excluded from the cache key.
`pre_run`	`list[string]`	yes	Shell lines run before the test binary. When non-empty, the target switches from the `exec` driver to the `bash` driver so the lines execute as shell.
`runner`	`string` (target address)	yes	Exec runner the test runs under, overriding the plugin's own `runner` option for this package's tests. See Running Go tools under a runner.

Link configuration

The link struct configures the build (binary) target generated for a package main. It applies to the exact declaring package by default; add recursive = True to extend it to descendant packages.

When multiple applicable states carry link, their values accumulate shallow-to-deep: a recursive ancestor's flags, deps, and runtime deps are collected first, then the package's own. For deps and runtime_deps, accumulation happens per dep group — see Naming dep groups.

BUILD
provider_state(
    provider = "go",
    link = {
        "flags":        ["-X main.version=1.2.3", "-s"],
        "deps":         ["//embed:assets"],
        "runtime_deps": ["//data:config"],
    },
)

Field	Type	Hashed	Description
`flags`	`list[string]`	yes	Extra flags passed verbatim to `go tool link`, inserted before `-o`. Use for `-X` linker vars, stripping flags (`-s`, `-w`), etc.
`deps`	`string \| list[string] \| map[string, string \| list[string]]`	yes	Target addresses staged into the link sandbox as hashed inputs. `flags` can reference their outputs.
`runtime_deps`	`string \| list[string] \| map[string, string \| list[string]]`	no	Target addresses staged with the binary at run time only. Not hashed — they do not affect the cache key.

Unknown keys in the link map are rejected with a clear error naming the unrecognized field.

Naming dep groups

A single address, or a list of addresses, lands in the default group and is staged in the sandbox under the link_deps / link_runtime_deps key:

BUILD
provider_state(
    provider = "go",
    link = {"deps": ["//embed:assets", "//embed:more"]},
)

Pass a map instead to split deps or runtime_deps into named groups. Each key is used verbatim as the sandbox key its addresses are staged under, and a map value can be a single address string or a list:

BUILD
provider_state(
    provider = "go",
    link = {
        "deps": {
            "assets": ["//embed:assets"],
            "icons":  "//embed:icons",   # a bare string is a single-address group
        },
    },
)

The same group name declared on a recursive ancestor and on the package itself merges shallow-to-deep; different group names stay separate.

note

Named groups are staged verbatim, so avoid reusing the plugin's own internal group names (link_deps, link_runtime_deps, lib_*, gosdk) — a collision merges your addresses into that internal group instead of a distinct one.

Claude Code plugin

heph-go is a Claude Code plugin focused on Go under heph: it teaches Claude to enable the provider and drivers, wire generated code (go_src / go_codegen_root / go_codegen_deps) and test fixtures (go_test_data), and keep :build / :test green.

It ships from this docs site, which doubles as a plugin marketplace.

Install

Run both commands inside Claude Code:

Claude Code
/plugin marketplace add hephbuild/hephbuild.github.io
/plugin install heph-go@heph-marketplace

The first command registers the marketplace from this repository; the second installs the plugin. Restart Claude Code if prompted.

What you get

Piece	What it does
Skill `heph-go`	Auto-activates whenever Claude works on Go under heph — enabling the provider and the `go_golist` / `go_compile` / `go_testmain` drivers, building and testing packages, wiring `go_src` / `go_embed_src` / `go_codegen_root` / `go_codegen_deps` / `go_embed_deps` and `go_test_data`, pinning `gotool`, or debugging missing generated code, embeds, modules, or testdata. Carries this page's reference bundled.
Agent `heph-go-expert`	A specialist subagent for non-trivial Go-in-heph jobs: standing up the provider, wiring cross-package codegen, staging fixtures, or diagnosing why a `:build` / `:test` fails to see what it needs.
`/heph-go-setup`	Turn on and configure Go support — provider, the three drivers, `gotool`, and `skip`.
`/heph-go-codegen`	Wire generated code and test fixtures into a package via `go_src`, `go_codegen_root`, `go_codegen_deps`, and `go_test_data`.
`/heph-go-check`	Audit a workspace's Go setup — drivers enabled, `gotool` / `skip` sane, generated code and fixtures wired, `:build` / `:test` green — and fix what isn't.

The skill activates on its own — you don't invoke it. Type a command with its leading slash; address the agent by name ("ask the heph-go-expert to…").

tip

The plugin's bundled knowledge mirrors this page. When an exact option or label matters, the skill fetches the matching .md doc live (indexed at llms.txt), so it stays current even between plugin updates.

For general heph support beyond Go, install heph-expert the same way — see the Claude Code plugin guide.

Update

Pull the latest marketplace catalog, then upgrade:

Claude Code
/plugin marketplace update heph-marketplace
/plugin install heph-go@heph-marketplace

Uninstall

Claude Code
/plugin uninstall heph-go@heph-marketplace

Driver​

Enabling it​

Configuration​

Options​

Toolchain modes​

Skipping directories​

Running Go tools under a runner​

Usage​

Race detector​

Linting and formatting​

Selecting and configuring linters​

Suppressing findings​

Formatters​

Pinning the analyzer binary​

Provider functions​

Build variants​

Buildmode: static vs PIE​

Selecting a variant​

Generated code and test data​

go_src — generated source​

go_embed_src — embed assets excluded from package analysis​

go_test_data — test fixtures​

Generated dependency addresses​

provider_state — per-package configuration​

Recognized keys​

Skipping tests​

Skipping lint​

Test environment​

Link configuration​

Naming dep groups​

Claude Code plugin​

Install​

What you get​

Update​

Uninstall​

Driver

Enabling it

Configuration

Options

Toolchain modes

Skipping directories

Running Go tools under a runner

Usage

Race detector

Linting and formatting

Selecting and configuring linters

Suppressing findings

Formatters

Pinning the analyzer binary

Provider functions

Build variants

Buildmode: static vs PIE

Selecting a variant

Generated code and test data

`go_src` — generated source

`go_embed_src` — embed assets excluded from package analysis

`go_test_data` — test fixtures

Generated dependency addresses

provider_state — per-package configuration

Recognized keys

Skipping tests

Skipping lint

Test environment

Link configuration

Naming dep groups

Claude Code plugin

Install

What you get

Update

Uninstall