Cache Action

Save and restore files as a cache in GitHub Actions. Use this project to cache dependencies or build outputs to speed up GitHub Actions workflows.

This project comprises two components: a GitHub Action that can be used directly in workflows and a JavaScript library that contains functions for use in a JavaScript Action.

Using the GitHub Action

Use the following snippet to include the action in a GitHub workflow:

- name: Cache Dependencies
  uses: threeal/[email protected]
  with:
    key: a-key
    version: a-version
    files: a-file another-file

By default, the action will attempt to restore files from a cache if it exists; otherwise, it will save files to a cache at the end of the workflow run.

To restore and save the cache in separate steps, refer to the restore and save sub-actions.

Available Inputs

Name	Value Type	Description
`key`	String	The cache key.
`version`	String	The cache version.
`files`	Multiple Strings	The files to be cached, separated by spaces or newlines.

Available Outputs

Name	Value Type	Description
`restored`	`true` or `false`	A boolean value indicating whether the cache was successfully restored.

Example Usage

The following example demonstrates how to use the action to cache Node.js dependencies in a GitHub Action workflow:

name: Build
on:
  push:
jobs:
  build-project:
    name: Build Project
    runs-on: ubuntu-22.04
    steps:
      - name: Checkout Project
        uses: actions/[email protected]

      - name: Cache Dependencies
        id: cache-deps
        uses: threeal/[email protected]
        with:
          key: node-deps
          version: ${{ hashFiles('package-lock.json') }}
          files: node_modules

      - name: Install Dependencies
        if: steps.cache-deps.outputs.restored == 'false'
        run: npm install

      # Do something

This action will attempt to restore a cache with the key node-deps and a version specified by the hash of the package-lock.json file. If the cache exists, it will restore the node_modules directory and skip dependency installation. Otherwise, it will install the dependencies and save the node_modules to the cache at the end of the workflow run.

Using the JavaScript Library

Install the JavaScript library using a package manager:

npm install cache-action

Import the functions using the import statement:

import { restoreCache, saveCache } from "cache-action";

const restored = await restoreCache("a-key", "a-version");
if (!restored) {
  // Do something...

  await saveCache("a-key", "a-version", ["a-file", "another-file"]);
}

The library provides two functions: restoreCache for restoring files from a cache and saveCache for saving files to a cache. Refer to the library documentation here for more details on function usage.