GitHub Actions cache by puzl.cloud

This action allows local caching of dependencies and build outputs to improve workflow execution time when using GitHub Actions runners on puzl.cloud.

Usage

Pre-requisites

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

Inputs

• path - A list of files, directories, and wildcard patterns to cache and restore. See @actions/glob for supported patterns.
• key - An explicit key for restoring and saving the cache.
• restore-keys - An ordered list of prefix-matched keys to use for restoring stale cache if no cache hit occurred for key.

Outputs

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

Note: cache-hit will be set to true only when 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

Cache scopes

The cache is scoped to the key, version and branch. The default branch cache is available to other branches.

See Matching a cache key for more info.

Example workflow

Restoring and saving cache using a single action:

name: Caching Primes

on: push

jobs:
  build:
    runs-on: puzl-ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Cache Primes
        id: cache-primes
        uses: puzl-cloud/github-actions-cache@v4
        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

Using a combination of restore and save actions

name: Caching Primes

on: push

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

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

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: puzl-cloud/github-actions-cache@v4
    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 "::set-output name=date::$(/bin/date -u "+%Y%m%d")"
    shell: bash

  - uses: puzl-cloud/github-actions-cache@v3
    with:
      path: path/to/dependencies
      key: ${{ runner.os }}-${{ steps.get-date.outputs.date }}-${{ hashFiles('**/lockfiles') }}

See Using contexts to create cache keys

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 the 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: puzl-cloud/github-actions-cache@v4
    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 puzl-cloud/github-actions-cache must match the id in the if statement (i.e. steps.[ID].outputs.cache-hit)