Skip to main content

​
Overview

Go’s build cache keeps local development fast, but CI starts every job with an empty cache and compiles everything from scratch. Blacksmith connects Go’s native cache protocol (GOCACHEPROG) to a cache shared across runs, workflows, and machines, so go build, go test, and go vet reuse prior work automatically. There are no cache actions to add, no cache keys to manage, and no GOFLAGS changes to make. Go build caching requires Go 1.24 or newer. Older toolchains do not support this integration, so keep your existing build cache for jobs that use them.

​
How it works

Go hashes every package build against its inputs: source files, dependencies, build tags, compiler flags, and the toolchain version. Blacksmith stores each result under that hash. When a later run builds a package whose hash matches, Go links the cached object instead of compiling. The same applies to go vet facts, and optionally to passing test results. A change invalidates only the packages it reaches through the import graph, so a one-line edit recompiles a handful of packages while the rest of the build reads from cache. Each repository has its own cache, shared across branches and pull requests, so merging to main warms the cache for every branch that follows. Caches are separated by CPU architecture and never shared across repositories or organizations.

​
Enable Go build caching

An organization admin can enable Go build caching from Settings > Features in the Blacksmith dashboard. Find Go build cache under Caching.

​
Replacing actions/cache

Go build caching completely replaces the Actions cache for your Go jobs. If your workflows cache Go builds or tests with actions/cache or actions/setup-go today, remove that caching and enable Go build caching instead. Your jobs skip the cache download and upload entirely and get faster builds.

​
Test result caching

Go test cache is an organization-wide option under Go build cache. When it is on, a test that passed in one run replays as (cached) in later runs with unchanged inputs, so retries and merge queue runs skip tests they already passed. It is off by default because caching is only safe for hermetic tests. Go tracks the environment variables and files a test reads and re-runs it when any of them change, but it cannot see external state like databases, network services, or the clock. If your suites depend on that kind of state, leave this off, or opt out for a single job:
Tests run with -count=1 are never cached, matching stock go test.

​
Verify cache hits

Go doesn’t announce build cache hits in its output; the visible signals are faster go build steps and (cached) markers in test output. For the full picture, open the Cache page, choose a repository, and open the Go tab. Hit rate there counts what your builds actually experienced, whether a hit was served from the runner’s local store or the shared cache. The first builds populate the cache, so compare hit rate and step durations across later runs.