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.


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.


name: Tests
    runs-on: namespace-profile-my-profile
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Install Go
        uses: actions/setup-go@v5
          cache: false # Skip remote GitHub caching
      - name: Setup Go cache
        uses: namespacelabs/nscloud-cache-action@v1
          cache: go
      - name: Go tests
        run: go test ./...



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.


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


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

Learn from our community how to get the best caching performance for your setup.

Join Discord

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.


See the following snippet for a working example.

name: NPM tests on Playwright
    runs-on: namespace-profile-my-profile-for-containers
      image: mcr.microsoft.com/playwright:v1.39.0
        NSC_CACHE_PATH: ${{ env.NSC_CACHE_PATH }} # env.NSC_CACHE_PATH contains the path to Cache Volume directory, that is `/cache`.
        - /cache:/cache # Where the Cache Volume is mounted.
      options: --cap-add=SYS_ADMIN # Required to by nscloud-cache-action to call `mount`.
      - 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
          path: |
      - 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.


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.


    name: Build Widgets
    runs-on: nscloud
    # These permissions are needed to interact with GitHub's OIDC Token endpoint.
      id-token: write
      contents: read
      - uses: actions/checkout@v4
      - uses: namespacelabs/nscloud-setup@v0
      - name: Save build output cache
        id: cache-output
        uses: namespacelabs/nscloud-cache-action@v0
          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