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:

Enabling mode go caches Go modules and Go build artifacts.

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

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 NPM cache
        uses: namespacelabs/nscloud-cache-action@v1
        with:
          path: |
            ~/.npm
            ./node_modules
 
      - name: Install dependencies and run tests
        run: |
          npm install
          npm run test