Go Build Cache
Avrea accelerates Go builds using GOCACHEPROG
(Go 1.24+), which redirects the Go build cache to a colocated remote store.
Repeated builds across jobs and branches only recompile what changed.
On Avrea runners
Section titled “On Avrea runners”The environment variables are pre-configured:
GOCACHEPROG="/usr/local/bin/avrea-build-cache gocache"BUILD_CACHE_URL="http://cache.avrea.com:8290"Your workflow needs no changes:
jobs: build: runs-on: avrea-ubuntu-latest steps: - uses: actions/checkout@v7 - uses: actions/setup-go@v7 with: go-version: '1.25' cache: false # Use Avrea build cache instead - run: go build ./... - run: go test ./...Requirements
Section titled “Requirements”- Go 1.24 or later:
GOCACHEPROGwas introduced in Go 1.24.
Manual setup
Section titled “Manual setup”For non-standard runner images:
- name: Verify build cache binary run: | if [ ! -x /usr/local/bin/avrea-build-cache ]; then echo "::warning::avrea-build-cache not found, falling back to local cache" echo "GOCACHEPROG=" >> "$GITHUB_ENV" fi
- run: go build ./...Known limitations
Section titled “Known limitations”With GOCACHEPROG set, go tool -n <tool> prints a temporary path that no
longer exists once the command returns, because Go keeps tool binaries only in
its local cache. Build scripts that capture that path and run it later, such as
the OpenTelemetry Collector Contrib Makefiles, fail with
No such file or directory. Running go tool <tool> or go run directly is
unaffected.
To work around it, build the tool to a fixed path and run that:
go build -o bin/mytool example.com/cmd/mytoolOr turn the build cache off for that step only:
- run: make generate env: GOCACHEPROG: ""How it works
Section titled “How it works”GOCACHEPROG tells the Go toolchain to use an external program for cache
storage instead of the local filesystem. The avrea-build-cache gocache adapter
translates Go's cache protocol into HTTP requests against the build cache.
Cache stats
Section titled “Cache stats”Run and job cache stats show Go cache traffic and, for supported jobs, a build-client summary split into local and remote operations. The summary does not include package, source file, or function names. See Cache Stats for field definitions and coverage states.