Skip to content
Documentation

Docs / Adapter commands / Go

Go adapter

Connect Go's build and test cache to a shared workspace through GOCACHEPROG. Go keeps generating the action and output identities it already uses.

Command
boringcache go
Protocol
Go GOCACHEPROG over /gocache/*
Action
mode: go

How the adapter works

Go-native cache hook

BoringCache uses GOCACHEPROG rather than archiving Go's cache directory after the fact.

Local and CI reuse

The same workspace can serve a developer shell and fresh CI runner.

Works with Docker-heavy Go repos

Go cache can sit beside Docker BuildKit cache when Go builds also happen inside images.

Set up Go

Keep the command and cache tag in .boringcache.toml, then use the same boringcache go entrypoint locally and in CI.

[adapters.go]
tag = "go-cache"
command = ["go", "test", "./..."]

# Run: boringcache go

Before the first run

  • Use Go 1.24 or newer for the stable GOCACHEPROG path.
  • Run ordinary go build or go test commands after the adapter is active.
  • The next CLI offers source-freshness = true under [adapters.go.options] for wrapped commands such as boringcache go -- go test ./.... It verifies tracked source bytes and restores unchanged file and directory timestamps before Go runs. This can preserve test-result reuse after a fresh checkout at the same absolute path.
  • Source freshness is off by default and adds source hashing before and after the command. It requires Git and applies to tracked inputs under the command's working directory; untracked files, symlinks and directories with unverified contents retain their timestamps. Use a wrapped CLI command for this option; Action mode: go and Docker tool-cache injection do not support it.
  • Keep the hidden cache-program helper out of scripts; boringcache go is the supported entrypoint.

Go build actions

What is recorded

The CLI adds -debug-actiongraph after go build, go install, go test, go run and go vet, and after a leading -C directory flag when the command has one. After the command, Go writes its action graph to a temporary file, and the CLI reads it and removes it. The flag does not change Go's action IDs, so cache keys and cache hits are unchanged.

The run page and the run API list every build action: its package and mode, when it was ready, started and finished, its CPU time, the actions it depended on, and whether Go ran a command for it, reused its result from the cache, or found its output already up to date. Go's graph does not say whether a test run or vet check ran or came from Go's test cache, so those actions have an unknown outcome. They also show the chain of actions in which each was the last dependency to finish before the next started.

Every request Go makes to the cache is recorded too, with its result, size and time, so a run shows both what Go built and what the cache served. Go does not report which cache entry an action used, and the chain of last dependencies is not an estimate of time saved.

Commands without build actions

A command that passes its own -debug-actiongraph keeps its file, and the CLI records no actions. Commands that build nothing, such as go mod download, and commands run through another program, such as make, record only the cache requests.

Use the same adapter in GitHub Actions

The Action exports GOCACHEPROG for later Go commands, keeps the cache service available during the job, and closes it cleanly afterward.

.github/workflows/ci.yml
- uses: boringcache/one@1781572d7b3ec5aef652f8ba479b981439b2776b # v1.48.2
  with:
    trust-policy: auto
    mode: go

- run: go test ./...

Approve the repository through Connect CI and grant the job contents: read and id-token: write. The Action uses that Machine connection. Pull requests restore by default; trusted jobs may publish. See the authentication example in the GitHub Actions reference for scoped credentials when OIDC is unavailable.

GitHub Actions reference

Benchmarks

Hugo builds the same upstream commits with BoringCache, Depot Cache and GHA Cache on the same runner classes.

Hugo

Go

Benchmark →

Static site generator written in Go.

Average restore, build and save · lower is better

GitHub runner

4 vCPU · 16 GB · Ubuntu 24.04 x86-64

BoringCache
41.9 s 18 builds
Depot Cache
91.6 s 18 builds
GHA Cache
41.1 s 18 builds
Same CPU model

Builds of one commit can land on different CPU models. These ratios use only the build pairs where both caches ran on the same model; above 1.00× means BoringCache's total time over those pairs was lower.

Depot Cache vs BoringCache
2.26× · 7 of 18
GHA Cache vs BoringCache
0.97× · 11 of 18
5 CPU models recorded
BoringCache · Build cache
AMD EPYC 7763 (11 builds) · AMD EPYC 9V45 (4 builds) · AMD EPYC 9V74 (2 builds) · Intel Xeon 6973P-C (1 build)
Depot Cache
AMD EPYC 7763 (9 builds) · AMD EPYC 9V45 (4 builds) · AMD EPYC 9V74 (2 builds) · Intel Xeon Platinum 8370C (2 builds) · Intel Xeon 6973P-C (1 build)
GHA Cache · Local cache directory restored and saved by actions/cache
AMD EPYC 7763 (9 builds) · AMD EPYC 9V45 (6 builds) · AMD EPYC 9V74 (1 build) · Intel Xeon Platinum 8370C (1 build) · Intel Xeon 6973P-C (1 build)
Cold and warm builds

Each table is one workflow run with one build per cache. A row marked Different CPU ran on another CPU model than BoringCache at the same level, so part of its time difference can come from the hardware.

One cold and warm build per cache
Cache Cold Warm CPU
BoringCache Build cache 89.2 s 20.0 s Cold: AMD EPYC 9V74 · Warm: Intel Xeon Platinum 8573C
Depot Cache 1 min 52 s 81.7 s Cold: AMD EPYC 9V45 · Warm: Intel Xeon Platinum 8370C Different CPU
GHA Cache Local cache directory restored and saved by actions/cache 88.3 s 6.3 s Cold: AMD EPYC 7763 · Warm: AMD EPYC 9V45 Different CPU

Cache hits

BoringCache · GitHub runner · 4 vCPU

88.2% of 35,305 lookups over 18 builds

Served from the runner
Under 1 ms per read
Read from cache
9.4 GB

Tool reference

Check the tool's own reference when you need cache-key rules, build settings, or version-specific behavior.

All adapter commands

Compare every supported command, protocol, and Action mode in one place.

Adapter command index →

Need help or found something unclear? Open an issue or browse the CLI repo.