Skip to content

pleo-io/s3-cache-action

Repository files navigation

🪣 ♻️ S3 Cache Action

First Run, Cold Cache Next Run, Cache Hit
On the first run, the action reports no cache and the long task is done. On the next run, the action reports cache hit, and the long task is skipped

Description

Allows to skip a job if it already succeeded for the same repo state. Uses S3 for caching.

This action works for workflow runs across different branches, which is not currently possible using actions/cache.' This allows to e.g. safely skip work after merging to the main branch, if the code was tested/linted/built on a feature branch already.

How It Works

It saves a cache/${repoOwner}/${repoName}/${keyPrefix}/${treeHash} file in an S3 bucket, where treeHash is the current root tree hash of the git repo (i.e. the output of git rev-parse HEAD:). If the GitHub workflow job is ran with the same state of the repository after succeeding once, you can avoid any work by checking the processed output of this action which will be set to true.

Since GitHub Actions do not yet support early exits from jobs, you'll need to check the value of the processed output of this action for every step in the job that you want to avoid.

Note that the action assumes that the AWS credentials have already been configured for the job, and allow to read and write to the S3 bucket provided as input. Use the aws-actions/configure-aws-credentials action in a step prior to running this action to ensure that's the case.

Note that the action requires actions/checkout to be run before it is invoked. This is required in order to determine the repo state.

Inputs

parameter description required default
bucket-name Name of the S3 bucket to use for storing cache files. The job needs to have AWS credentials configured to allow read/write from this bucket. true
key-prefix Key prefix to add to the cache files key. By default the job ID is used. The full key used for the cache files is cache/${repoOwner}/${repoName}/${keyPrefix}/${treeHash} false ${{ github.job }}
custom-hash Hash calculated on the user's side used as part of the cache key for the job run. false
aws-region AWS region for the S3 bucket used for cache files. available. true
aws-access-key-id Access Key ID for an IAM user with permissions to read/write to the S3 bucket used for cache files. true
aws-secret-access-key Secret Access Key for an IAM user with permissions to read/write to the S3 bucket used for cache files. true

Outputs

parameter description
processed Indicates if the job has already been performed for the current repo state.
hash The repo tree hash which was used for caching.

Example Use

- uses: aws-actions/configure-aws-credentials@v1
  with:
      # See aws-actions/configure-aws-credentials docs
- uses: pleo-io/s3-cache-action@v3
  id: s3-cache
  with:
      bucket-name: my-s3-bucket
      aws-region: eu-west-1
      aws-access-key-id: 'aws-access-key-id'
      aws-secret-access-key: 'aws-secret-access-key'
- run: make very-long-lint
  if: steps.s3-cache.outputs.processed == 'false'
- run: make very-long-test
  if: steps.s3-cache.outputs.processed == 'false'

Runs

This action is a node20 action.

Contributing

  • Fork this repository
  • Install dependencies
yarn
  • Make changes
  • Test your changes
make test
  • Lint your changes
make lint
  • Build the action
make build
  • Commit the built Action
  • Submit a PR

PR titles must follow the Conventional Commits spec.