Caching

WarpBuild provides a fast, unlimited cache for GitHub Action runners. This cache can be used to store build artifacts, dependencies, and other files that are needed across builds. The cache is designed to be fast, reliable, and secure.

⚠️ Read First

GitHub has made updates to caching for improved performance and unlimited size. You can change the size limits and the expiration policy here: https://github.com/organizations/$YOURORG/settings/actions.

This is already available for most users and is expected to GA by the end of 2025: Increased Cache Size in Actions GA and recent commitment from the team.

This provides the most seamless experience for users and is the recommended approach. However, for some advanced use case and BYOC, you may still want to use WarpBuild cache. Read on.

Usage

WarpBuild cache can be used by replacing the actions/cache@v4 action with the warpbuilds/cache action. The warpbuilds/cache action is fully compatible with the actions/cache@v4 action and can be used as a drop-in replacement.

Refer to the WarpBuild Actions cache documentation for more information on how to use the cache.

uses: WarpBuilds/cache@v1

The cache is designed to be fast, reliable, and secure. It is available on all WarpBuild runners and is enabled by default.

Examples

Restoring and saving cache using a single action

name: Caching Primes

on: push

jobs:
  build:
    runs-on: warp-ubuntu-latest-x64-4x

    steps:
      - uses: actions/checkout@v3

      - name: Cache Primes
        id: cache-primes
        uses: WarpBuilds/cache@v1
        with:
          path: prime-numbers
          key: ${{ runner.os }}-primes

      - name: Generate Prime Numbers
        if: steps.cache-primes.outputs.cache-hit != 'true'
        run: /generate-primes.sh -d prime-numbers

      - name: Use Prime Numbers
        run: /primes.sh -d prime-numbers

The cache action provides a cache-hit output which is set to true when the cache is restored using the primary key and false when the cache is restored using restore-keys or no cache is restored.

Using a combination of restore and save actions

name: Caching Primes

on: push

jobs:
  build:
    runs-on: warp-ubuntu-latest-x64-4x

    steps:
      - uses: actions/checkout@v3

      - name: Restore Cache Primes
        id: cache-primes-restore
        uses: WarpBuilds/cache/restore@v1
        with:
          path: |
            path/to/dependencies
            some/other/dependencies
          key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}

      - name: Install Dependencies
        if: steps.cache-primes-restore.outputs.cache-hit != 'true'
        run: /install.sh

      - name: Save Cache Primes
        id: cache-primes-save
        uses: WarpBuilds/cache/save@v1
        with:
          path: |
            path/to/dependencies
            some/other/dependencies
          key: ${{ steps.cache-primes-restore.outputs.cache-primary-key }}

Inputs

• key - An explicit key for restoring and saving the cache.
• path - A list of files, directories, and wildcard patterns to cache and restore.
• restore-keys - An ordered list of keys to use for restoring stale cache if no cache hit occurred for key.
• enableCrossOsArchive - An optional boolean when enabled, allows windows runners to save or restore caches that can be restored or saved respectively on other platforms. Default: false
• fail-on-cache-miss - Fail the workflow if cache entry is not found. Default: false
• lookup-only - If true, only checks if cache entry exists and skips download. Does not change save cache behavior. Default: false
• delete-cache - If true, deletes the cache entry. Skips restore and save. Default: false

Outputs

• cache-hit - A boolean value to indicate an exact match was found for the key.

  Note cache-hit will only be set to true when a cache hit occurs for the exact key match. For a partial key match via restore-keys or a cache miss, it will be set to false.

See Skipping steps based on cache-hit for info on using this output

Creating a cache key

A cache key can include any of the contexts, functions, literals, and operators supported by GitHub Actions.

For example, using the hashFiles function allows you to create a new cache when dependencies change.

- uses: WarpBuilds/cache@v1
  with:
    path: |
      path/to/dependencies
      some/other/dependencies
    key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}

Additionally, you can use arbitrary command output in a cache key, such as a date or software version:

# http://man7.org/linux/man-pages/man1/date.1.html
- name: Get Date
  id: get-date
  run: |
    echo "date=$(/bin/date -u "+%Y%m%d")" >> $GITHUB_OUTPUT
  shell: bash

- uses: WarpBuilds/cache@v1
  with:
    path: path/to/dependencies
    key: ${{ runner.os }}-${{ steps.get-date.outputs.date }}-${{ hashFiles('**/lockfiles') }}

See Using contexts to create cache keys

Cache scopes

The cache is scoped to the key, version, and branch.

See Matching a cache key for more info.

Docker Layer Caching

It is recommended to use the new Docker Builders for a faster and better build experience.

Since WarpBuild Cache seamlessly integrates as a drop-in replacement for GitHub Actions Cache, you can easily use it for Docker Layer Caching.

Step 1: Set Up Docker Buildx Action

Ensure that the Docker Buildx Action is included in your workflow file if it isn't already. This step is essential to enable the GHA backend for Docker Layer Caching.

Note: Don't forget to include the driver-opts key as shown below.

- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v3
  with:
    driver-opts: |
      network=host

Step 2: Configure Docker Build Push Action

Update the cache-from and cache-to fields by setting the url to http://127.0.0.1:49160/, as shown below. Ensure that the type is set to gha and version is set to 1. WarpBuild Cache will automatically proxy the storage backend for docker layer caching.

Note: It is recommended to set mode=max. This setting ensures that all layers, including intermediate steps, are cached. For more details, read about the mode here.

Note: It is mandatory to set version=1 for the cache to work.

- name: Docker WarpCache Backend
  uses: docker/build-push-action@v6
  with:
    context: .
    push: false
    tags: "alpine/warpcache:latest"
    cache-from: type=gha,url=http://127.0.0.1:49160/,version=1
    cache-to: type=gha,url=http://127.0.0.1:49160/,mode=max,version=1

That's all there is to it! With these adjustments, WarpBuild Cache is now set up as your Docker Layer Caching backend.

Advanced Configuration

Running inside a container

A few conditions must be met to use the cache action inside a custom container.

• wget: the cache action uses wget to download the cache. See our workflow file for an example.
• zstd: the downloaded cache is uncompressed using zstd.
• WARPBUILD_RUNNER_VERIFICATION_TOKEN: This environment variable is always present in WarpBuild runners and is used to authenticate the action with the WarpBuild service. To use WarpCache inside a container, pass the WARPBUILD_RUNNER_VERIFICATION_TOKEN environment variable to the container as shown below.

test-proxy-save:
  runs-on: warp-ubuntu-latest-x64-16x
    container:
      image: ubuntu:latest
      env:
        WARPBUILD_RUNNER_VERIFICATION_TOKEN: ${{ env.WARPBUILD_RUNNER_VERIFICATION_TOKEN }}

Known practices and workarounds

There are a number of community practices/workarounds to fulfill specific requirements. You may choose to use them if they suit your use case. Note these are not necessarily the only solution or even a recommended solution.

• Cache segment restore timeout
• Update a cache
• Use cache across feature branches
• Cross OS cache
• Cross Arch cache
• Deletion of Caches

Cache Version

Cache version is a hash generated for a combination of compression tool used (Gzip, Zstd, etc. based on the runner OS) and the path of directories being cached. If two caches have different versions, they are identified as unique caches while matching. This, for example, means that a cache created on a warp-macos-14-arm64-6x runner can't be restored on warp-ubuntu-latest-x64-4x as cache versions are different.

Caching Strategies

With the introduction of the restore and save actions, a lot of caching use cases can now be achieved. Please see the caching strategies document for understanding how you can use the actions strategically to achieve the desired goal.

Skipping steps based on cache-hit

Using the cache-hit output, subsequent steps (such as install or build) can be skipped when a cache hit occurs on the key. It is recommended to install missing/updated dependencies in case of a partial key match when the key is dependent on the hash of the package file.

Example:

steps:
  - uses: actions/checkout@v3

  - uses: WarpBuilds/cache@v1
    id: cache
    with:
      path: path/to/dependencies
      key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}

  - name: Install Dependencies
    if: steps.cache.outputs.cache-hit != 'true'
    run: /install.sh

Note The id defined in WarpBuilds/cache must match the id in the if statement (i.e. steps.[ID].outputs.cache-hit)

Troubleshooting

Errors in Cache restore

To troubleshoot cache restore issues, rerun your workflow with debug logging enabled. Check for any warnings or errors in the restore step that match those described below.

Note: Using versions older than v1.4.5 might cause issues with cache saves and restores for some customers.

zstd version: null followed by a 404 warning

Each cache entry has a unique version associated with it (See: Cache Version), which is matched during the restore process. The zstd version: null warning indicates that the default compression tool, zstd, is not available in the current environment. Consequently, the action falls back to using gzip compression. (This warning can be ignored if the cache was originally saved using gzip.)

Since all warpbuild runners have zstd available, this warning typically occurs when running the action inside a container that lacks zstd.

To resolve this issue, ensure that the compression tools available in the current environment match those used when the cache was saved. If the cache was saved in a container with zstd and you attempt to restore it in a container without zstd, the restore will fail.

Failed to commit cache (Docker)

This error occurs usually when the docker layers are large and the runner size is small. For example, if you are using the 2x runner and some of the docker layers are larger than 5GB, you will likely encounter this error.

To resolve this issue, please upgrade to a larger runner size.

Limitations

• WarpBuild Caching is not supported for windows based runners WarpBuild runners.

Expiry

Cache is set to expire after 7 days of last use. It can be manually deleted at any time from the action or using the console.

Pricing