local-cache

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

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.

The utilities tar and pigz needs to be included and accessible in the execution path of your self-hosted runner.

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.

Environment Variables

• CACHE_DIR - Directory local to your self-hosted runner for where to store your cached files. This is set to /media/cache by default.

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

name: Caching Primes

on: push

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3

    - name: Cache Primes
      id: cache-primes
      uses: j3hempsey-actions/local-cache@v3
      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

Note: You must use the cache 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: actions/cache@v3
    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: 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

Cache Limits

Cache limits are defined by the amount of disk space on your self-hosted runners. This job will not automatically monitor and clean up disk usage and an additional workflow will be required for handling automatic cache cleanup.

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

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

Contributing

We would love for you to contribute to j3hempsey-actions/local-cache, pull requests are welcome! Please see the CONTRIBUTING.md for more information.

License

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