37 lines
2.1 KiB
Markdown
37 lines
2.1 KiB
Markdown
# gha-cache
|
|
|
|
`gha-cache` provides an async API to the GitHub Actions Cache API.
|
|
You can upload blobs with `AsyncRead` streams and obtain presigned URLs to download them.
|
|
|
|
## Introduction
|
|
|
|
The GitHub Actions Cache (hereinafter GHAC) service stores binary blobs [identified](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#matching-a-cache-key) by the following 3-tuple:
|
|
|
|
- **Cache Key**: The developer-specified name of the blob.
|
|
- **Cache Version**: A string identifying conditions that affect compatibility of the blob. It works like a namespace.
|
|
- The official implementation uses a SHA256 hash of the paths and the compression method, but it can be anything.
|
|
- In this crate, we let the user feed in arbitrary bytes to mutate the hash.
|
|
- **Cache Scope**: The branch containing the workflow run that uploaded the blob
|
|
|
|
### APIs
|
|
|
|
Two sets of APIs are in use:
|
|
|
|
- [GitHub Actions Cache API](https://github.com/actions/toolkit/blob/457303960f03375db6f033e214b9f90d79c3fe5c/packages/cache/src/internal/cacheHttpClient.ts#L38): Private API used by GHAC. This API allows uploading and downloading blobs.
|
|
- Endpoint: `$ACTIONS_CACHE_URL`
|
|
- Token: `$ACTIONS_RUNTIME_TOKEN`
|
|
- [GitHub REST API](https://docs.github.com/en/rest/actions/cache?apiVersion=2022-11-28#delete-github-actions-caches-for-a-repository-using-a-cache-key): Public API. This API allows listing and deleting blobs.
|
|
- Endpoint: `$GITHUB_API_URL` / `https://api.github.com`
|
|
- Token: `${{ secrets.GITHUB_TOKEN }}`
|
|
|
|
This crate supports only the former API.
|
|
We should contribute support for the latter to [Octocrab](https://github.com/XAMPPRocky/octocrab).
|
|
|
|
## Quick Start
|
|
|
|
Since GHAC uses private APIs that use special tokens for authentication, we need to get them from a workflow run.
|
|
|
|
The easiest way is with the `keygen` workflow in this repo.
|
|
Generate an `age` encryption key with `nix shell nixpkgs#age --command age-keygen -o key.txt`, and add the Public Key as a repository secret named `AGE_PUBLIC_KEY`.
|
|
Then, trigger the `keygen` workflow which will print out a command that will let you decrypt the credentials.
|