Go - Namespace Documentation

Documentation Index

Fetch the complete documentation index at: /docs/llms.txt

Use this file to discover all available pages before exploring further.

Assistant

Responses are generated using AI and may contain mistakes.

Use nscloud-cache-action to retain Go modules and build outputs on a Cache Volume. Start with this setup to reuse cached files across jobs. For workloads that also need to share build outputs across machines, see advanced caching below.

Cache Go in GitHub Actions

Enable a Cache Volume on your runner profile, then configure the action after checkout and Go installation:

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:

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:

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:

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:

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

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.

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:

unset GOCACHEPROG

Last modified onSeptember 22, 2026

Ctrl+I

Documentation Index

​ Cache Go in GitHub Actions

​ Advanced: gocacheprog-based incremental caching

​ Install gocacheprog

​ Authentication

​ Enable remote caching

​ Local files

​ Persist configuration across workflow steps

​ Cache configuration

​ Verify cache use