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.

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.

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: Setup 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:

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

path

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

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

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.

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

GitHub Cache Action Compatibility Mode

namespacelabs/nscloud-cache-action can be also used as a drop-in replacement for GitHub cache action that offers improved performance and reliability.

In this mode it does not use Namespace cache volumes feature, but still addresses the recurring problems of downloads and uploads stalling indefinitely.

Prerequisites

In order to use nscloud-cache-action@v0, you need to have access to Namespace. Add a namespacelabs/nscloud-setup step to authenticate with Namespace.

Example

jobs:
  build:
    name: Build Widgets
    runs-on: nscloud
    # These permissions are needed to interact with GitHub's OIDC Token endpoint.
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: namespacelabs/nscloud-setup@v0
 
      - name: Save build output cache
        id: cache-output
        uses: namespacelabs/nscloud-cache-action@v0
        with:
          key: build-output
          path: ./out
 
      - name: Perform expensive build
        run: ./build.sh
        if: steps.cache-output.outputs.cache-hit != 'true'
 
      - name: Observe cached files
        run: ls -l ./out