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

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:

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

Note

Set cache: false on actions/setup-go to avoid redundant GitHub Actions cache uploads - the build cache already handles artifact caching more efficiently.

Requirements

• Go 1.24 or later: GOCACHEPROG was introduced in Go 1.24.

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

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

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.