nscloud-cache-action - Namespace Documentation

namespacelabs/nscloud-cache-action@v1

Namespace platform provides Cache Volumes feature that allows workflows to share data across invocations. The action performs necessary wiring to store cacheable workflow data on the attached Cache Volume. The action works by linking the listed directories to directories in the mounted cache volume (using bind-mounts on Linux and symbolic links on macOS). The content written to the cached directories will be transparently stored on the mounted cache volume. This way the action does not need to spend time explicitly downloading and uploading cache content to remote locations.

Prerequisites

In order to use nscloud-cache-action, you need to ensure that a cache volume is attached to the GitHub Actions job. Check out the Cache Volumes guide for details. When using a package manager or toolchain cache mode (for example npm, pnpm, or go), the manager or toolchain must be installed before the cache action runs, otherwise the step fails. This does not apply to caching arbitrary files with path.

It is important to run the cache action after the checkout action in the workflow sequence. Checkout action automatically wipes the workspace directory, so it would remove the cached content and prevent new content from being stored on the cache volume.

Examples

Select languages and frameworks
Cache arbitrary files

name: Tests
jobs:
  tests:
    runs-on: namespace-profile-my-profile

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install Go
        uses: actions/setup-go@v6
        with:
          cache: false # Skip remote GitHub caching

      - name: Set up Go cache
        uses: namespacelabs/nscloud-cache-action@v1
        with:
          cache: go

      - name: Go tests
        run: go test ./...

name: Tests
jobs:
  tests:
    runs-on: namespace-profile-my-profile

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install Go
        uses: actions/setup-go@v6
        with:
          cache: false # Skip remote GitHub caching

      - name: Set up Go cache
        uses: namespacelabs/nscloud-cache-action@v1
        with:
          path: |
            /home/runner/.cache/go-build
            /home/runner/go/pkg/mod

      - name: Go tests
        run: go test ./...

Options

detect

string A list of cache modes to enable only if detected in the environment. Set to true to detect all available cache modes. See cache for a list of available cache modes. Optional.

cache

string A list caching modes to enable. Currently supported languages/frameworks are:

AptCache mode apt caches downloaded APT packages on the attached Cache Volume.The apt-config executable must be available before namespacelabs/nscloud-cache-action is called.

- name: Set up apt cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: apt

BunCache mode bun caches downloaded packages on the attached Cache Volume.To enable bun cache mode, the executable must be available before namespacelabs/nscloud-cache-action is called.When using oven-sh/setup-bun, no additional configuration is needed:

- name: Setup Bun
  uses: oven-sh/setup-bun@v2

Now you can cache bun packages across runs.

- name: Set up bun cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: bun

CocoaPodsCache mode cocoapods caches CocoaPods cache on the attached Cache Volume.This mode caches ./Pods and ~/Library/Caches/CocoaPods.

- name: Set up cocoapods cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: cocoapods

ComposerCache mode composer caches downloaded packages which Composer retains in a global Cache, on the attached Cache Volume.To enable composer cache mode, the executable must be available before namespacelabs/nscloud-cache-action is called.When using shivammathur/setup-php, no additional configuration is needed:

- name: Setup PHP
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.3'

Composer stores zip archives of downloaded PHP packages in a global cache. The cache action retains this global cache on the attached Cache Volume.

- name: Set up composer cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: composer

DenoCache mode deno caches downloaded packages on the attached Cache Volume.To enable deno cache mode, the executable must be available before namespacelabs/nscloud-cache-action is called.When using denoland/setup-deno, disable its built-in cache:

- name: Setup Deno
  uses: denoland/setup-deno@v2
  with:
    cache: false

Now you can cache Deno packages across runs. The cache action stores the Deno cache directory (from deno info --json) on the attached Cache Volume.

- name: Set up deno cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: deno

GoCache mode go caches Go modules and Go build artifacts on the attached Cache Volume.To enable go cache mode, the executable must be available before namespacelabs/nscloud-cache-action is called.When using actions/setup-go, disable its built-in cache:

- name: Setup Go
  uses: actions/setup-go@v5
  with:
    go-version-file: go.mod
    cache: false

Now you can cache Go modules and build artifacts across runs. The cache action stores GOCACHE and GOMODCACHE on the attached Cache Volume.

- name: Set up go cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: go

GolangCI-LintCache mode golangci-lint caches analysis results on the attached Cache Volume. Combine this with the go cache mode, as GolangCI-Lint will make use of the Go build cache to speed up things further.To enable golangci-lint cache mode, the golangci-lint executable must be available before namespacelabs/nscloud-cache-action is called.Typically you achieve this by first installing golangci-lint:

- name: Setup golangci-lint
  uses: golangci/golangci-lint-action@v8
  with:
    version: 2.8
    install-only: true
    skip-cache: true

Next, setup the cache:

- name: Set up golangci-lint cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: golangci-lint

To finish you can either call golangci-lint manually, or through the action (skipping the install step):

- name: Setup golangci-lint
  uses: golangci/golangci-lint-action@v8
  with:
    version: 2.8
    install-mode: none

GradleCache mode gradle caches Gradle build artifacts on the attached Cache Volume.When using actions/setup-java, disable its built-in cache:

- name: Setup Java
  uses: actions/setup-java@v5
  with:
    distribution: temurin
    java-version: '21'
    cache: ''

Now you can cache Gradle build artifacts across runs. The cache action stores ~/.gradle/caches and ~/.gradle/wrapper on the attached Cache Volume.

- name: Set up gradle cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: gradle

HomebrewCache mode brew retains Homebrew artifact downloads across runs.The brew executable must be available before namespacelabs/nscloud-cache-action is called. This is available by default on macOS runners.

- name: Set up brew cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: brew

MavenCache mode maven caches Maven artifacts on the attached Cache Volume.When using actions/setup-java, disable its built-in cache:

- name: Setup Java
  uses: actions/setup-java@v5
  with:
    distribution: temurin
    java-version: '21'
    cache: ''

Now you can cache Maven artifacts across runs. The cache action stores ~/.m2/repository on the attached Cache Volume, which contains remote downloads and temporary build artifacts.

- name: Set up maven cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: maven

MiseCache mode mise caches downloaded tools on the attached Cache Volume.First setup the cache before installing Mise:

- name: Set up mise cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: mise

Now setup Mise and install packages, making sure to disable its built-in cache:

- name: Setup mise
  uses: jdx/mise-action@v2
  with: 
    cache: false

NixCache mode nix caches the Nix store and user cache on the attached Cache Volume.First setup the cache before installing Nix:

- name: Set up nix cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: nix

Now install Nix. The /nix store will already be mounted from the cache:

- name: Install Nix
  uses: cachix/install-nix-action@v31
  with:
    extra_nix_config: |
      access-tokens = github.com=${{ secrets.GITHUB_TOKEN }}
      system-features = kvm nixos-test

NPMCache mode npm caches downloaded packages on the attached Cache Volume.To enable npm cache mode, the executable must be available before namespacelabs/nscloud-cache-action is called.When using actions/setup-node, make sure to disable its built-in caching with package-manager-cache: false:

- name: Setup Node
  uses: actions/setup-node@v6
  with:
    package-manager-cache: false

Now you can cache npm packages across runs.

- name: Set up npm cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: npm

PlaywrightCache mode playwright stores the downloaded browsers on the attached Cache Volume.The cache action detects the browser cache directory automatically based on the platform.

- name: Set up playwright cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: playwright

See the example repo for a working example.

PNPMCache mode pnpm caches downloaded packages on the attached Cache Volume.To enable pnpm cache mode, the executable must be available before namespacelabs/nscloud-cache-action is called.When using pnpm/action-setup, no additional configuration is needed:

- name: Setup pnpm
  uses: pnpm/action-setup@v4

Now you can cache pnpm packages across runs.

- name: Set up pnpm cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: pnpm

PoetryCache mode poetry caches downloaded packages on the attached Cache Volume.To enable poetry cache mode, the executable must be available before namespacelabs/nscloud-cache-action is called.One way of achieving that is via pipx:

- name: Install Poetry
  run: pipx install poetry

Now you can cache Poetry packages across runs.

- name: Set up poetry cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: poetry

PythonCache mode python retains the pip cache directory across runs.The pip executable is available by default on GitHub runners.

- name: Set up python cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: python

RubyCache mode ruby caches Bundler packages on the attached Cache Volume.When using ruby/setup-ruby, disable its built-in cache:

- name: Setup Ruby
  uses: ruby/setup-ruby@v1
  with:
    ruby-version: '3.2'
    bundler-cache: false

Now you can cache Bundler packages across runs.

- name: Set up ruby cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: ruby

RustCache mode rust caches Cargo registry, git dependencies, and build artifacts on the attached Cache Volume.When using actions-rust-lang/setup-rust-toolchain, disable its built-in cache:

- name: Setup Rust
  uses: actions-rust-lang/setup-rust-toolchain@v1
  with:
    cache: false

Now you can cache Rust packages across runs.

- name: Set up rust cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: rust

SwiftPMCache mode swiftpm caches Swift Package Manager build artifacts and module cache on the attached Cache Volume.The cache action stores ./.build, ~/Library/Caches/org.swift.swiftpm, and ~/Library/org.swift.swiftpm on the attached Cache Volume.

- name: Set up swiftpm cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: swiftpm

UVCache mode uv caches downloaded packages on the attached Cache Volume.To enable uv cache mode, the executable must be available before namespacelabs/nscloud-cache-action is called.When using astral-sh/setup-uv, disable its built-in cache:

- name: Setup uv
  uses: astral-sh/setup-uv@v5
  with:
    enable-cache: false

Now you can cache uv packages across runs.

- name: Set up uv cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: uv

XcodeCache mode xcode caches Xcode’s DerivedData and Compilation Cache on the attached Cache Volume.The xcodebuild executable is available by default on macOS runners. This cache mode also enables Xcode’s Compilation Cache feature.

- name: Set up xcode cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: xcode

YarnTo enable yarn cache mode, the executable must be available before namespacelabs/nscloud-cache-action is called.You can enable Yarn using Corepack (included with Node.js), making sure to not set a cache value:

- name: Setup Node
  uses: actions/setup-node@v4
  with:
    node-version: '22'
    cache: ''

- name: Enable Corepack
  run: corepack enable

Yarn stores every package in a global cache. The cache action retains this global cache on the attached Cache Volume. The cache location is detected automatically based on Yarn version (v1 uses yarn cache dir, v2+ uses yarn config get cacheFolder).

- name: Set up yarn cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: yarn

You can enable multiple caching modes and can also add additional paths to the cache using path.

- name: Set up Go and Rust cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: |
      go
      rust

path

string A list of files, directories, to cache and restore. ~ is resolved to $HOME. Can be used in concert with cache.

- name: Set up Go cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    path: |
      /home/runner/.cache/go-build
      /home/runner/go/pkg/mod

Note: Contents of ${{ runner.temp }} cannot be cached as this directory is emptied at the beginning and end of each job.

fail-on-cache-miss

boolean If enabled, fail the workflow if the path is not found on the cache volume.

Advanced: Running GitHub Jobs in Containers

We recommend using a separate profile for your workflows that run in containers.GitHub Actions run as user runner by default. Running in a container can change the user. Sharing caches from different users may lead to permission errors when accessing the cache.Details →

When using containers to run GitHub Jobs, extra configuration is required to make the cache action work correctly.

The Cache Volume path /cache must be mounted into the container.
The env var NSC_CACHE_PATH must be set.
Container needs to have SYS_ADMIN capability, so that the cache action has permissions to call the mount command.
The sudo, mkdir and chown binaries must be available in the container image, or must be installed.

This action relies on specific properties of the environment and may require tuning to work with images that significantly diverge from Ubuntu. Please reach out to us at support@namespace.so for assistance.

See the following snippet for a working example.

name: NPM tests on Playwright
jobs:
  tests:
    runs-on: namespace-profile-my-profile-for-containers

    container:
      image: mcr.microsoft.com/playwright:v1.39.0
      env:
        NSC_CACHE_PATH: ${{ env.NSC_CACHE_PATH }} # env.NSC_CACHE_PATH contains the path to Cache Volume directory, that is `/cache`.
      volumes:
        - /cache:/cache # Where the Cache Volume is mounted.
      options: --cap-add=SYS_ADMIN # Required to by nscloud-cache-action to call `mount`.

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install sudo
        run: |
          apt-get update -y && apt-get install -y sudo

      - name: Setup PNPM cache
        uses: namespacelabs/nscloud-cache-action@v1
        with:
          cache: pnpm

      - name: Install dependencies and run tests
        run: |
          pnpm install
          pnpm run test

​Prerequisites

​Examples

​Options

​detect

​cache

​path

​fail-on-cache-miss

​Advanced: Running GitHub Jobs in Containers

Prerequisites

Examples

Options

detect

cache

path

fail-on-cache-miss

Advanced: Running GitHub Jobs in Containers