> ## Documentation Index
> Fetch the complete documentation index at: https://namespace.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Go

> Cache Go modules and build outputs on Cache Volumes, with early-access remote caching for incremental builds across machines.

Use [nscloud-cache-action](/docs/reference/github-actions/nscloud-cache-action) to retain Go modules and build outputs on a [Cache Volume](/docs/architecture/storage/cache-volumes). Start with this setup to reuse cached files across jobs. For workloads that also need to share build outputs across machines, see [advanced caching](#advanced-gocacheprog-based-incremental-caching) below.

## Cache Go in GitHub Actions

Enable a Cache Volume on your [runner profile](/docs/solutions/github-actions/caching#using-a-cache-volume), then configure the action after checkout and Go installation:

```yaml theme={null}
name: Go tests
on: [push, pull_request]

jobs:
  test:
    runs-on: namespace-profile-my-profile
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-go@v6
        with:
          go-version-file: go.mod
          cache: false
      - uses: namespacelabs/nscloud-cache-action@v1
        with:
          cache: go
      - run: go test ./...
```

Replace `namespace-profile-my-profile` with your profile's label. `cache: false` disables `setup-go`'s GitHub-hosted cache; `cache: go` mounts Go's build cache (`GOCACHE`) and module download cache (`GOMODCACHE`) on the Cache Volume.

## Advanced: gocacheprog-based incremental caching

`gocacheprog` is an early-access alternative to Go's built-in build-cache handling. It **builds on Cache Volumes**, adding a shared remote cache behind the local files on the volume. Builds read local outputs first, fetch missing outputs from the remote cache, and share new outputs across machines.

### Install gocacheprog

`gocacheprog` implements Go's external build-cache protocol. It requires Go 1.24 or later and supports Linux and macOS on amd64 and arm64. It does not install Go or move compilation to another machine.

Install the latest released binary:

```bash theme={null}
curl -fsSL https://public.namespaceblobs.com/gocacheprog/install.sh | sh
```

### Authentication

No additional authentication setup is required for jobs running on Namespace. `gocacheprog` automatically uses the credentials already provided to the job.

### Enable remote caching

Tell Go to launch the helper for builds and tests:

```bash theme={null}
export GOCACHEPROG="\"$HOME/.local/bin/gocacheprog\""
go build ./...
go test ./...
```

Go starts and stops the helper itself. Do not run it as a background daemon: it communicates with Go over standard input and output.

The helper creates or reuses a Segcache instance in the job's site, backed by a Cache Volume. Jobs in the same tenant and site share the instance using the default tag `main`. Set `-tag` to choose another instance. No separate provisioning command or client certificate setup is required.

Instance provisioning retries for up to five minutes. After provisioning, the helper waits up to five seconds for the cache endpoint to respond. Provisioning failures are reported to Go; an endpoint that remains unavailable produces cache misses instead.

### Local files

The helper checks local files before fetching remote outputs and stores new build outputs locally.

The local directory is `ns-gocacheprog` under `NSC_CACHE_PATH` when available, otherwise under the OS user cache directory. On Linux this is `XDG_CACHE_HOME` or `~/.cache`; on macOS it is `~/Library/Caches`. Set `-cache-dir` to choose a different parent directory:

```bash theme={null}
export GOCACHEPROG="\"$HOME/.local/bin/gocacheprog\" -cache-dir \"$HOME/.cache/namespace-go\""
go build ./...
```

`GOCACHEPROG` uses the helper's local directory for build outputs, not the build-cache directory mounted by `cache: go`. The helper can still use the same Cache Volume through `NSC_CACHE_PATH`.

There is no automatic local eviction. Budget disk space for build outputs and downloads, and remove old helper cache files only when no Go process is using them. Remote eviction does not remove files already downloaded for an active build.

### Persist configuration across workflow steps

In GitHub Actions, an `export` affects only the current step. After installing the helper, add its configuration to `GITHUB_ENV` for subsequent steps:

```yaml theme={null}
- name: Enable remote Go build caching
  shell: bash
  run: |
    printf 'GOCACHEPROG="%s/.local/bin/gocacheprog"\n' "$HOME" >> "$GITHUB_ENV"
- run: go build ./...
- run: go test ./...
```

### Cache configuration

Use `-concurrency` to limit concurrent remote requests. The default is 4; supported values are 1 through 128. `-namespace` defaults to `gocache` and groups keys within the cache without creating a separate instance.

<Warning>
  A cache namespace separates keys, not permissions. Use separate cache instances and local directories for different trust boundaries. Do not give untrusted fork jobs write access to a cache consumed by trusted builds.
</Warning>

### Verify cache use

The helper prints the same cache report at shutdown regardless of the backend. `Get` and `Put` show request counts, human-readable sizes, and p50/p90 latency. `Actions` shows local and remote misses and writes. `Objects` shows local disk hits, download wait time, and upload/download counts, sizes, and latency.

To check remote reuse, build the same source with the same Go version, platform, and build flags on a fresh machine or with a fresh `-cache-dir`. Running twice with the same local directory can demonstrate local reuse without exercising the remote cache.

Use `-log-file` to redirect helper logs or `-silent` to suppress the final statistics. To return to Go's built-in cache in the current shell:

```bash theme={null}
unset GOCACHEPROG
```