# Go Build Cache

import { Aside } from '@astrojs/starlight/components';

Avrea accelerates Go builds using [`GOCACHEPROG`](https://pkg.go.dev/cmd/go/internal/cacheprog)
(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:

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

Your workflow needs no changes:

```yaml title="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 ./...
```

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

## Requirements

- **Go 1.24 or later**: `GOCACHEPROG` was introduced in Go 1.24.

## Manual setup

For non-standard runner images:

```yaml
- 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](/cache/stats/) for field definitions and coverage states.