WarpCache Action

This action allows caching dependencies and build outputs to improve workflow execution time.

Two other actions are available in addition to the primary cache action:

• Restore action
• Save action

Documentation

WarpCache is a performant drop-in replacement to GitHub's actions/cache. See Performance comparison @ WarpBuild Docs

For more information on how to leverage caching in GitHub workflows, see "Caching dependencies to speed up workflows".

What's New

v1

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

• Provides feature parity with GitHub's actions/cache v4.
• Provides unlimited cache for a repo.
• Supports enableCrossArchArchive to allow runners to save or restore caches that can be restored or saved respectively on runners of other architectures.
• Supports enableCrossOsArchive to allow runners to save or restore caches that can be restored or saved respectively on other operating systems.
• Allows delete-cache input to delete the cache from the action directly.

Usage

Pre-requisites

WarpCache will only work when used with WarpBuild's Runners. Sign up @ https://www.warpbuild.com/.

Create a workflow .yml file in your repository's .github/workflows directory. An example workflow is available below. For more information, see the GitHub Help Documentation for Creating a workflow file.

Inputs

• key - An explicit key for a cache entry. See creating a cache key.

• path - A list of files, directories, and wildcard patterns to cache and restore. See @actions/glob for supported patterns.

• restore-keys - An ordered multiline string listing the prefix-matched keys, that are used 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

• enableCrossArchArchive - An optional boolean when enabled, allows runners to save or restore caches that can be restored or saved respectively on runners of other architectures. Default: false

  Note: GitHub's actions/cache does not have this option and allows cross-architecture caching by default. In WarpCache, cross-architecture support requires explicitly setting enableCrossArchArchive: true.

• 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

Environment Variables

• SEGMENT_DOWNLOAD_TIMEOUT_MINS - Segment download timeout (in minutes, default 10) to abort download of the segment if not completed in the defined number of minutes. Read more

Outputs

• cache-hit - A string value to indicate an exact match was found for the key.
  • If there's a cache hit, this will be 'true' or 'false' to indicate if there's an exact match for key.
  • If there's a cache miss, this will be an empty string.

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

Cache scopes

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

See Matching a cache key for more info.

Example cache workflow

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@v4

    - 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@v4

    - name: Restore cached Primes
      id: cache-primes-restore
      uses: WarpBuilds/cache/restore@v1
      with:
        path: |
          path/to/dependencies
          some/other/dependencies
        key: ${{ runner.os }}-primes
    .
    . //intermediate workflow steps
    .
    - name: Save 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 }}

Note You must use the cache or restore action in your workflow before you need to use the files that might be restored from the cache. If the provided key matches an existing cache, a new cache is not created and if the provided key doesn't match an existing cache, a new cache is automatically created provided the job completes successfully.

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.

Implementation Examples

Every programming language and framework has its own way of caching.

See Examples for a list of WarpBuilds/cache implementations for use with:

• Bun
• C# - NuGet
• Clojure - Lein Deps
• D - DUB
• Deno
• Elixir - Mix
• Go - Modules
• Haskell - Cabal
• Haskell - Stack
• Java - Gradle
• Java - Maven
• Node - npm
• Node - Lerna
• Node - Yarn
• OCaml/Reason - esy
• PHP - Composer
• Python - pip
• Python - pipenv
• R - renv
• Ruby - Bundler
• Rust - Cargo
• Scala - SBT
• Swift, Objective-C - Carthage
• Swift, Objective-C - CocoaPods
• Swift - Swift Package Manager
• Swift - Mint

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 Limits

There is no enforced cache limit on WarpCache.

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@v4

  - 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)

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.

Pro tip: The list caches API can be used to get the version of a cache. This can be helpful to troubleshoot cache miss due to version.

Example

The workflow will create 3 unique caches with same keys. Ubuntu and mac runners will use different compression technique and hence create two different caches. And `build-linux` will create two different caches as the `paths` are different.

jobs:
  build-linux:
    runs-on: warp-ubuntu-latest-x64-4x
    steps:
      - uses: actions/checkout@v4

      - name: Cache Primes
        id: cache-primes
        uses: WarpBuilds/cache@v1
        with:
          path: prime-numbers
          key: primes

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

      - name: Cache Numbers
        id: cache-numbers
        uses: WarpBuilds/cache@v1
        with:
          path: numbers
          key: primes

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

  build-mac:
    runs-on: warp-macos-14-arm64-6x
    steps:
      - uses: actions/checkout@v4

      - name: Cache Primes
        id: cache-primes
        uses: WarpBuilds/cache@v1
        with:
          path: prime-numbers
          key: primes

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

Running inside a container

To use WarpCache inside a container, pass the WARPBUILD_RUNNER_VERIFICATION_TOKEN environment variable to the container as shown below. This environment variable is always present in WarpBuild runners and is used to authenticate the action with the WarpBuild service.

Note: Ensure that wget is installed in the container, as it is used by the action to download the cache. See our workflow file for an example.

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

Windows environment variables

Please note that Windows environment variables (like %LocalAppData%) will NOT be expanded by this action. Instead, prefer using ~ in your paths which will expand to the HOME directory. For example, instead of %LocalAppData%, use ~\AppData\Local. For a list of supported default environment variables, see the Learn GitHub Actions: Variables page.

Note

Thank you for your interest in this GitHub repo, however, right now we are not taking contributions.

We continue to focus our resources on strategic areas that help our customers be successful while making developers' lives easier. While GitHub Actions remains a key part of this vision, we are allocating resources towards other areas of Actions and are not taking contributions to this repository at this time. The GitHub public roadmap is the best place to follow along for any updates on features we’re working on and what stage they’re in.

We are taking the following steps to better direct requests related to GitHub Actions, including:

1. We will be directing questions and support requests to our Community Discussions area

2. High Priority bugs can be reported through Community Discussions or you can report these to our support team https://support.github.com/contact/bug-report.

3. Security Issues should be handled as per our security.md.

We will still provide security updates for this project and fix major breaking changes during this time.

You are welcome to still raise bugs in this repo.

Attribution

A big thank you to the GitHub team for their amazing work on the actions/cache.

License

The scripts and documentation in this project are released under the MIT License