logo

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

Reach out to the team to learn how to get the best caching performance for your setup.

Email the team

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.

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

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

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

This mode is DEPRECATED. It is still maintained for the existing customers but will not be enabled for new users.

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