Go - ReasonOS Documentation

rbs builds Go with a hermetic, downloaded toolchain — no Go installation on the host is required. Compilation always runs offline: third-party modules are fetched once into a shared workspace cache (verified against your committed go.sum) or read from a committed vendor/ tree, and the compiler itself can never reach the network. The Go rules live in two modules:

load("@rbs//go/rules.rbs", "go_binary", "go_library", "go_test", "go_deps_consistency")
load("@rbs//go/proto.rbs", "go_proto_library")

Declaring the Go toolchain

Declare the toolchain once in your workspace’s WORKSPACE.rbs. rbs downloads the matching Go SDK for your platform on first build and reuses it from a shared store afterwards.

Declare the toolchain in WORKSPACE.rbs

load("@rbs//go/toolchain.rbs", "go_toolchain")

go_toolchain(
    name = "go",
    version = "1.25.6",
)

Build a Go target

rbs build //services/myservice:myservice

The first build downloads the Go SDK; subsequent builds are fully offline.

go_toolchain accepts:

Parameter	Type	Default	Required	Meaning
`name`	string	`"go"`	no	Toolchain name. Keep the default unless you have a reason not to — the Go rules look up the toolchain named `go`.
`version`	string	`"1.24.3"`	no	Go version to download. Currently supported: `1.24.3`, `1.25.6`. An unsupported version fails at load time and lists the available ones.
`register`	bool	`True`	no	Register the toolchain for the workspace (leave on).
`platform_override`	string	`None`	no	Pin the toolchain to a specific platform instead of the current target platform.
`download_host`	bool	`True`	no	Also download the host platform’s SDK when it differs from the target platform.

The Go rules never auto-download a different Go version mid-build. If a go.mod declares a go directive newer than the workspace toolchain, the build fails with the Go tool’s own version error — bump version in WORKSPACE.rbs instead.

If no Go toolchain is declared, the rules fall back to whatever go is on your PATH. That works for quick experiments but is not hermetic — declare the toolchain for anything you share or ship.

Rules

go_binary

Builds a Go main package into a runnable binary. Sources (plus go.mod/go.sum for module builds) are staged into an isolated build workspace; the build runs with the network disabled.

Attribute	Type	Default	Required	Meaning
`name`	string	—	yes	Target name.
`srcs`	label list	`[]`	no	Go sources, plus `go.mod`/`go.sum` for module builds. A committed `vendor/` tree is optional — without one, dependencies are fetched from the module proxy and verified against `go.sum`.
`deps`	label list	`[]`	no	Local `go_library` dependencies (staged as sources).
`goflags`	string list	`[]`	no	Extra flags passed to `go build`.
`pkg`	string	`"."`	no	Main package path within the module, e.g. `"./cmd/myservice"`.
`cgo`	bool	`False`	no	Opt in to CGO. Off by default so builds never depend on a host C toolchain. Cannot be combined with `goos`/`goarch`.
`goos`	string	`""`	no	Target OS for cross-compilation (e.g. `"linux"`). Empty means the host platform.
`goarch`	string	`""`	no	Target architecture for cross-compilation (e.g. `"amd64"`, `"arm64"`). Empty means the host platform.

A typical service target uses a standard Go module layout — a thin main under cmd/, everything else under internal/:

load("@rbs//go/rules.rbs", "go_binary")

_module_srcs = glob([
    "cmd/**/*.go",
    "internal/**/*.go",
]) + ["go.mod", "go.sum"]

go_binary(
    name = "myservice",
    srcs = _module_srcs,
    pkg = "./cmd/myservice",
)

rbs build //services/myservice:myservice
rbs run //services/myservice:myservice

go_library

Packages Go sources under a name so other targets can depend on them. It does not compile a separate archive — the consuming go_binary or go_test compiles all sources together.

Attribute	Type	Default	Required	Meaning
`name`	string	—	yes	Target name.
`srcs`	label list	`[]`	no	Go source files (and optionally `go.mod`/vendor files).
`deps`	label list	`[]`	no	Local `go_library` dependencies.
`cgo`	bool	`False`	no	Accepted for API parity with `go_binary`; compilation is handled by the consuming target.

load("@rbs//go/rules.rbs", "go_binary", "go_library")

go_library(
    name = "greeter",
    srcs = ["greeter.go"],
)

go_binary(
    name = "hello",
    srcs = ["main.go", "greeter.go"],
    deps = [":greeter"],
)

Within a single Go module, the simplest pattern is to glob the module’s sources directly into each go_binary/go_test target (as in the go_binary example above) — the Go compiler resolves package imports through the module path.

go_test

Runs go test hermetically over your module’s packages, with the same offline module resolution as go_binary. It is also the coverage entry point for rbs coverage.

Attribute	Type	Default	Required	Meaning
`name`	string	—	yes	Target name.
`srcs`	label list	—	yes	Go sources including `_test.go` files, plus `go.mod`/`go.sum` for module builds (a committed `vendor/` tree is optional). The rule fails if `srcs` is empty.
`deps`	label list	`[]`	no	Local `go_library` dependencies (staged as sources).
`goflags`	string list	`[]`	no	Extra flags passed to `go test`.
`packages`	string list	`["./..."]`	no	Package patterns to test.
`cgo`	bool	`False`	no	Opt in to CGO. Off by default.
`size`	string	`"medium"`	no	Test size: `small`, `medium`, or `large`.
`timeout`	int	`300`	no	Timeout in seconds (also passed as `go test -timeout`).
`min_line_coverage`	int	`0`	no	Minimum line coverage percentage — `rbs coverage` fails below it.
`coverage_exclude`	string list	`[]`	no	File patterns (e.g. `"*.pb.go"`) removed from coverage entirely — numerator and denominator. For machine-generated code only.

load("@rbs//go/rules.rbs", "go_test")

_module_srcs = glob([
    "cmd/**/*.go",
    "internal/**/*.go",
]) + ["go.mod", "go.sum"]

go_test(
    name = "test",
    srcs = _module_srcs,
    min_line_coverage = 80,
    coverage_exclude = ["*.pb.go"],
)

Stage every file your tests read at runtime. If tests load fixtures such as SQL migrations, add them to srcs (e.g. + glob(["migrations/*.sql"])) so they exist in the isolated test workspace.

go_deps_consistency

An opt-in gate for workspaces with multiple Go modules (one go.mod per service). It fails the build when two modules require the same dependency at different versions, naming every module, version, and file. Skip it if your workspace uses a single shared go.mod — drift is then impossible by construction.

Attribute	Type	Default	Required	Meaning
`name`	string	—	yes	Target name.
`go_mods`	label list	—	yes	`go.mod` files to cross-check — at least two.
`exempt`	string list	`[]`	no	Module paths allowed to differ between services. Each entry deserves a comment saying why.
`include_indirect`	bool	`False`	no	Also enforce `// indirect` requires (lockstep upgrades). Off by default — indirect versions legitimately differ between modules with different dependency graphs.

load("@rbs//go/rules.rbs", "go_deps_consistency")

go_deps_consistency(
    name = "go_deps_check",
    go_mods = [
        "billing/go.mod",
        "gateway/go.mod",
        "worker/go.mod",
    ],
)

When a conflict is found, the build fails with a fix-it message: align the versions (go get <module>@<version> && go mod tidy in each service) or list the module in exempt with a reason.

go_proto_library

Generates Go protobuf/gRPC code from .proto sources using the hermetic protoc and pinned protoc-gen-go / protoc-gen-go-grpc plugins. Generated .go files are written into the source tree (stamped DO NOT EDIT) so they can be committed next to the code that imports them — go_binary/go_test build from committed sources, so generated code must live beside them. Requires proto_toolchain() in WORKSPACE.rbs.

Attribute	Type	Default	Required	Meaning
`name`	string	—	yes	Target name.
`srcs`	label list	—	yes	`.proto` source files (package-relative paths).
`go_package`	string	—	yes	Must repeat the proto’s `option go_package` — used to flatten output paths.
`out_dirs`	string list	—	yes	Workspace-relative package directories to write generated `.go` files into. One copy per consuming module.

load("@rbs//go/proto.rbs", "go_proto_library")

go_proto_library(
    name = "go",
    srcs = ["v1/orders.proto"],
    go_package = "example.com/orders/internal/api/ordersv1",
    out_dirs = [
        "services/orders/internal/api/ordersv1",
        "services/gateway/internal/api/ordersv1",
    ],
)

Re-run the target (rbs build //proto/orders:go) after editing the .proto to refresh the committed stubs; catch drift in CI by regenerating and diffing.

Third-party dependencies

Go dependencies are declared exactly as Go expects — in your module’s go.mod and go.sum — and rbs resolves them hermetically. Compilation always runs with module fetching disabled, so dependencies must be on disk before the compiler starts. Which mode you are in follows from what you commit:

go.sum (default)
vendor/
No dependencies

Commit go.mod + go.sum (and list both in srcs), with no vendor/ tree. In a single network-enabled staging step, rbs downloads modules from the Go module proxy into a shared per-workspace cache, verifying every download against your committed go.sum. The build and all future builds then run offline against that cache.If go.sum is missing entries, the build fails and tells you to run go mod tidy and commit the result — incomplete checksums are never silently self-healed.

Commit a vendor/ tree (and include it in srcs). Builds run fully offline with -mod=vendor.vendor/modules.txt must be present — a vendor/ directory without it usually means vendoring is stale, so the build fails and asks you to run go mod vendor and commit the complete tree.

A module with go.mod but no go.sum builds offline as a zero-dependency module. The moment a real dependency appears, the build fails loudly until a complete go.sum is committed. Sources without any go.mod build in non-module mode — fine for small stdlib-only tools.

Private modules: downloads come from the module proxy only — there is no fallback to git or VCS credentials, so builds stay reproducible on any machine. Point the RBS_GOPROXY environment variable at an internal module proxy to resolve private modules.

Testing and coverage

Run tests with rbs test:

rbs test //services/myservice:test    # one target
rbs test //...                        # every test target in the workspace
rbs test :test --watch                # TDD: re-run on file changes

Enforce coverage thresholds with rbs coverage:

rbs coverage //services/myservice:test
rbs coverage //...

rbs coverage runs the tests with coverage instrumentation across all staged packages — untested packages count as 0% instead of silently dropping out — converts the Go cover profile to lcov, and fails the target if line coverage falls below min_line_coverage.

rbs test does not enforce coverage thresholds — it prints a reminder when a target declares them. Gate coverage in CI with rbs coverage.

Go coverage measures statements, so go_test exposes a line coverage threshold only — there are no branch or function thresholds that could never be measured.

Use coverage_exclude sparingly and only for machine-generated files (for example "*.pb.go" from go_proto_library) — excluded files disappear from both sides of the ratio, and the coverage log names every active exclusion so the narrowed denominator is never silent.

Cross-compilation

go_binary cross-compiles per target via the goos and goarch attributes — the standard workflow for packaging Linux images from a macOS workspace:

go_binary(
    name = "myservice_linux",
    srcs = _module_srcs,
    pkg = "./cmd/myservice",
    goos = "linux",
    goarch = "arm64",
)

oci_image(
    name = "image",
    binary = ":myservice_linux",
    base = "scratch",
    entrypoint = ["/app/myservice_linux/runfiles/_main/myservice_linux.bin"],
)

Rules of the road:

Two targets that differ only in goos/goarch are cached and built independently — they can never reuse each other’s output.
cgo = True cannot be combined with goos/goarch: cross-compiling CGO would need a target C toolchain, which rbs does not provide.
A cross-compiled binary is for packaging and deployment, not for running locally. Invoking it on a mismatched host prints a clear explanation instead of the kernel’s cryptic exec format error.
Container images stamp their os/arch from the packaged binary itself, so packaging a host-platform binary into a Linux-stamped image fails loudly rather than producing a lying image.

Caching

Go builds share one module cache and one build cache per workspace, so each dependency version downloads once and packages compile incrementally across all targets; completed build actions are additionally cached in the shared rbs store, so unchanged targets are not rebuilt at all.

Getting Started

Build

Languages

Containers & Deploy

Infrastructure

CI & Remote Builds

Team Workflow

Go

Declaring the Go toolchain

Rules

go_binary

go_library

go_test

go_deps_consistency

go_proto_library

Third-party dependencies

Testing and coverage

Cross-compilation

Caching

​Declaring the Go toolchain

​Rules

​go_binary

​go_library

​go_test

​go_deps_consistency

​go_proto_library

​Third-party dependencies

​Testing and coverage

​Cross-compilation

​Caching

Declaring the Go toolchain

Rules

go_binary

go_library

go_test

go_deps_consistency

go_proto_library

Third-party dependencies

Testing and coverage

Cross-compilation

Caching