namespacelabs/nscloud-cache-action

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.

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

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

Options

cache

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

Apt

Cache mode apt caches downloaded APT packages on the attached Cache Volume.

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

Cache mode cocoapods caches CocoaPods cache on the attached Cache Volume.

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

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

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

Enabling mode go caches Go modules and Go build artifacts.

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

Mode gradle caches the Gradle build cache, by retaining ~/.gradle/caches and ~/.gradle/wrapper on the attached Cache Volume.

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

Mode brew retains artifact downloads across runs.

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

Mode maven caches the local Maven repository, by retaining ~/.m2/repository on the attached Cache Volume. It caches remote downloads and contains temporary build artifacts that you have not yet released.

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

Cache mode playwright stores the downloaded browsers on the attached Cache Volume.

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

Mode pnpm caches the PNPM dependency store as returned by pnpm store path. Contents of node_modules are not cached as it is not always safe. During pnpm install the cached packages are copied into place.

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

Cache mode poetry retains Poetry's cache on the attached Cache Volume.

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

Mode python retains the cache directory configured in pip across runs.

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

Cache mode ruby retains Bundler cache on the attached Cache Volume.

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

Mode rust caches the directories ~/.cargo/registry, ~/.cargo/git, ./target, and ~/.cargo/.global-cache.

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

Cache mode swiftpm retains Swift Package Manager, ./.build and Xcode module cache on the attached Cache Volume.

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

Cache mode uv retains UV's cache on the attached Cache Volume.

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

Xcode stores all intermediate build artifacts, caches, and indexing information in the DerivedData directory. Cache mode xcode retains Xcode's DerivedData data on the attached Cache Volume.

This cache mode also enables Xcode 26 Compilation Cache feature. You will see cache stats in xcodebuild CompilationCacheMetrics action output.

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

Yarn stores every package in a global cache. Cache mode yarn retains this global cache on the attached Cache Volume.

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

  1. The Cache Volume path /cache must be mounted into the container.
  2. The env var NSC_CACHE_PATH must be set.
  3. Container needs to have SYS_ADMIN capability, so that the cache action has permissions to call the mount command.
  4. 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
Last updated