Skip to content

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.

The environment variables are pre-configured:

Terminal window
GOCACHEPROG="/usr/local/bin/avrea-build-cache gocache"
BUILD_CACHE_URL="http://cache.avrea.com:8290"

Your workflow needs no changes:

workflow.yml
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 ./...
  • Go 1.24 or later: GOCACHEPROG was introduced in Go 1.24.

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 ./...

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:

Terminal window
go build -o bin/mytool example.com/cmd/mytool

Or turn the build cache off for that step only:

- run: make generate
env:
GOCACHEPROG: ""

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.

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.