Caching in GitHub Actions

Accelerate your GitHub Actions workflows with Namespace's comprehensive caching solutions. Our caching capabilities dramatically reduce build times by persisting data across workflow runs, eliminating redundant downloads, builds, and computations. Namespace supports many frameworks and build systems natively through seamless integrations.

Cache Volumes

Cache Volumes are Namespace's high-performance caching solution that persists data across GitHub Actions runs. Unlike traditional caching solutions that require time-consuming uploads and downloads, Cache Volumes provide instant access to cached data through guaranteed cache locality. Cache Volumes support very high concurrency through automatic forking and scale up to hundreds of GB to match your project needs.

Enable caching

Go to the desired Runner Profile and enable caching.

The minimum cache size is 20 GB.

Use the cache in your workflow

The simplest way to start using the cache is to adopt nscloud-cache-action. The action supports many popular frameworks natively, but can also be used to cache arbitrary files or directories.

1. Add the action to your workflow and select which framework you use. You can enable caching for multiple frameworks simultaneously:

   - name: Configure Go and Rust cache
     uses: namespacelabs/nscloud-cache-action@v1
     with:
       cache: |
         go
         rust

   For a full list of supported frameworks, check out the action reference.

2. In case native support is not available yet, you can still make your framework work with Cache Volumes. Simply configure a list of paths to retain:

   - name: Configure custom cache
     uses: namespacelabs/nscloud-cache-action@v1
     with:
       path: |
         ~/.cache/custom-tool
         /opt/shared-libraries

   Our support team can help you identify the optimal cache configuration.

Container Images

Container Image caching allows you to dramatically reduce container startup times. When enabling this feature, both image layers and the often expensive unpacking are cached locally.

Faster pulls with one click

To enable container image caching, simply check the corresponding option in your runner profile configuration.

That's it! Repeated pulls of the same image will now complete in seconds rather than minutes.

Git Checkouts

Namespace can speed up your git checkouts by caching a mirror of your git repository. Checkout caching works best when cloning large repositories with many files. If you are also checking out submodules or rely on Git LFS, these are automatically cached, too.

Enable Git Checkout caching

Open your runner profile in the Dashboard and enable Git repository checkouts in the caching section.

Configure your workflow

To start using the newly enabled cache in your workflow, replace mentions of actions/checkout with nscloud-checkout-action:

jobs:
  tests:
    runs-on: namespace-profile-integration-tests
    steps:
      - name: Check out my repo
-       uses: actions/checkout@v4
+       uses: namespacelabs/nscloud-checkout-action@v7
        with:
          path: my-repo
      - run: | 
          cd my-repo && git status

Check out the action reference for a full list of supported options.

Toolchain Downloads

Cache downloads from setup actions like actions/setup-go, actions/setup-python, and actions/setup-node. These tools check AGENT_TOOLSDIRECTORY before downloading, and Namespace can automatically provide high-performance caching for these downloads.

Enable toolchain download caching

To start caching toolchain downloads, check the corresponding option in your profile configuration.

After enabling this option, most setup actions will already use the faster Namespace cache.

Optional: Skip GitHub's action cache

After enrolling Namespace's toolchain caching, you can disable GitHub's builtin action caching. This ensures that you avoid any superfluous network transfers, reducing the setup time of your workflow further.

- name: Setup Go
  uses: actions/setup-go@v5
  with:
    go-version: "1.21"
    cache: false # Use Namespace caching instead
 
- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: "18"
    cache: "" # Use Namespace caching instead

Advanced Cache Controls

Namespace cache volumes are separated at multiple levels to ensure security and prevent data leakage between different contexts.

Isolation Levels

Workspace Isolation: Each workspace maintains completely separate cache volumes. Caches from one workspace cannot be accessed by any other workspace, providing a strong security boundary between different organizational units or projects.

Runner Profiles: Different runner profiles use distinct cache volumes, even within the same workspace. This ensures that builds running on different profiles don't interfere with each other's cached data by default. Sharing the cache between two profiles is possible.

Repository: Each repository using a specific runner profile gets its own separate cache volume. The cache volume will be shared between all jobs running for a Git repository, but remains distinct from other repositories, even when they share the same runner profile configuration. Sharing the cache between two repositories is possible.

Custom Cache Identity

For scenarios requiring full control over the cache isolation boundary, you can specify custom cache tags using runner labels. Example using cache tags:

runs-on:
  - nscloud-ubuntu-22.04-arm64-4x16-with-cache
  - nscloud-cache-tag-my-custom-cache
  - nscloud-cache-size-100gb

Protect Caches from Updates

You can configure Cache Volumes to limit what git branches can perform updates to them. Restricting the source of cache updates is useful to avoid cache poisoning. When using this feature, all branches (including pull requests) can benefit from your cache, but only selected branches (e.g. main) may commit changes to it.

To specify which branches can update the cache volume, open the cache volume configuration, then check Show Advanced features, and finally type the branch names.

Any GitHub Actions job belonging to git branches that are not included in the allow-list, will be able to access the Cache Volumes, but their changes to the caches' content will not be persisted in the end. You may also use an asterisk as a placeholder to match a branch name pattern.

Build System Integrations

For advanced build systems, Namespace provides direct integrations that offer native, high-performance caching capabilities.

Don't see your build system? Reach out to our integrations team to learn about upcoming releases and join the early access.