actions/cache
2
0
Fork 0
mirror of https://github.com/actions/cache.git synced 2025-04-18 01:56:45 +00:00
Code Issues Projects Releases Packages Wiki Activity

Update documentation for save and restore

Browse source
This commit is contained in:
Dany Sam 2025-04-11 13:24:27 +05:30
parent 5b0b9687bc
commit d84d474ae1
2 changed files with 72 additions and 16 deletions
Download patch file Download diff file Expand all files Collapse all files

40
restore/README.md
View file

@ -1,6 +1,6 @@
# Restore action
# Restore Action with Google Cloud Storage Support
The restore action restores a cache. It works similarly to the `cache` action except that it doesn't have a post step to save the cache. This action provides granular ability to restore a cache without having to save it. It accepts the same set of inputs as the `cache` action.
The restore action restores a cache from Google Cloud Storage (GCS) with fallback to GitHub's cache backend. It works similarly to the main `cache` action except that it doesn't have a post step to save the cache. This action provides granular ability to restore a cache without having to save it. It accepts the same set of inputs as the main `cache` action.
## Documentation
@ -11,6 +11,30 @@ The restore action restores a cache. It works similarly to the `cache` action ex
* `restore-keys` - An ordered list of prefix-matched keys to use for restoring stale cache if no cache hit occurred for key.
* `fail-on-cache-miss` - Fail the workflow if cache entry is not found. Default: `false`
* `lookup-only` - If true, only checks if cache entry exists and skips download. Default: `false`
* `gcs-bucket` - Google Cloud Storage bucket name to use for caching. When provided, GCS will be used as the cache backend.
* `gcs-path-prefix` - Optional prefix path within the GCS bucket for cache files. Default: `github-cache`
### GCS Authentication
This action uses [Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials) to authenticate with Google Cloud. The recommended approach is to use the official Google Cloud auth action before using this action:
```yaml
- uses: google-github-actions/auth@v2
with:
# Using Service Account Key JSON (less secure)
credentials_json: ${{ secrets.GCP_CREDENTIALS }}
# Alternatively, use Workload Identity Federation (more secure)
# workload_identity_provider: ${{ secrets.WIF_PROVIDER }}
# service_account: ${{ secrets.WIF_SERVICE_ACCOUNT }}
```
For Workload Identity Federation, your workflow will need these permissions:
```yaml
permissions:
contents: 'read'
id-token: 'write' # Required for workload identity federation
```
### Outputs
@ -37,11 +61,12 @@ If you are using separate jobs to create and save your cache(s) to be reused by
steps:
- uses: actions/checkout@v4
- uses: actions/cache/restore@v4
- uses: danySam/gcs-cache/restore@v1
id: cache
with:
path: path/to/dependencies
key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
gcs-bucket: my-github-cache-bucket # Optional: Use GCS for caching
- name: Install Dependencies
if: steps.cache.outputs.cache-hit != 'true'
@ -69,11 +94,12 @@ steps:
- name: Build
run: /build-parent-module.sh
- uses: actions/cache/save@v4
- uses: danySam/gcs-cache/save@v1
id: cache
with:
path: path/to/dependencies
key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
gcs-bucket: my-github-cache-bucket # Optional: Use GCS for caching
```
#### Step 2 - Restore the built artifact from cache using the same key and path
@ -82,11 +108,12 @@ steps:
steps:
- uses: actions/checkout@v4
- uses: actions/cache/restore@v4
- uses: danySam/gcs-cache/restore@v1
id: cache
with:
path: path/to/dependencies
key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
gcs-bucket: my-github-cache-bucket # Optional: Use GCS for caching
- name: Install Dependencies
if: steps.cache.outputs.cache-hit != 'true'
@ -109,11 +136,12 @@ To fail if there is no cache hit for the primary key, leave `restore-keys` empty
steps:
- uses: actions/checkout@v4
- uses: actions/cache/restore@v4
- uses: danySam/gcs-cache/restore@v1
id: cache
with:
path: path/to/dependencies
key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
gcs-bucket: my-github-cache-bucket # Optional: Use GCS for caching
fail-on-cache-miss: true
- name: Build

48
save/README.md
View file

@ -1,6 +1,6 @@
# Save action
# Save Action with Google Cloud Storage Support
The save action saves a cache. It works similarly to the `cache` action except that it doesn't first do a restore. This action provides granular ability to save a cache without having to restore it, or to do a save at any stage of the workflow job -- not only in post phase.
The save action saves a cache to Google Cloud Storage (GCS) with fallback to GitHub's cache backend. This action provides the granular ability to save a cache without first having to restore it, or to save a cache at any stage of the workflow job—not only in the post phase.
## Documentation
@ -9,6 +9,30 @@ The save action saves a cache. It works similarly to the `cache` action except t
* `key` - An explicit key for a cache entry. See [creating a cache key](../README.md#creating-a-cache-key).
* `path` - A list of files, directories, and wildcard patterns to cache. See [`@actions/glob`](https://github.com/actions/toolkit/tree/main/packages/glob) for supported patterns.
* `upload-chunk-size` - The chunk size used to split up large files during upload, in bytes
* `gcs-bucket` - Google Cloud Storage bucket name to use for caching. When provided, GCS will be used as the cache backend.
* `gcs-path-prefix` - Optional prefix path within the GCS bucket for cache files. Default: `github-cache`
### GCS Authentication
This action uses [Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials) to authenticate with Google Cloud. The recommended approach is to use the official Google Cloud auth action before using this action:
```yaml
- uses: google-github-actions/auth@v2
with:
# Using Service Account Key JSON (less secure)
credentials_json: ${{ secrets.GCP_CREDENTIALS }}
# Alternatively, use Workload Identity Federation (more secure)
# workload_identity_provider: ${{ secrets.WIF_PROVIDER }}
# service_account: ${{ secrets.WIF_SERVICE_ACCOUNT }}
```
For Workload Identity Federation, your workflow will need these permissions:
```yaml
permissions:
contents: 'read'
id-token: 'write' # Required for workload identity federation
```
### Outputs
@ -31,11 +55,12 @@ steps:
- name: Build artifacts
run: /build.sh
- uses: actions/cache/save@v4
- uses: danySam/gcs-cache/save@v1
id: cache
with:
path: path/to/dependencies
key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
gcs-bucket: my-github-cache-bucket # Optional: Use GCS for caching
```
### Re-evaluate cache key while saving
@ -47,15 +72,16 @@ Let's say we have a restore step that computes a key at runtime.
#### Restore a cache
```yaml
uses: actions/cache/restore@v4
uses: danySam/gcs-cache/restore@v1
id: restore-cache
with:
key: cache-${{ hashFiles('**/lockfiles') }}
gcs-bucket: my-github-cache-bucket
```
#### Case 1 - Where a user would want to reuse the key as it is
```yaml
uses: actions/cache/save@v4
uses: danySam/gcs-cache/save@v1
with:
key: ${{ steps.restore-cache.outputs.cache-primary-key }}
```
@ -63,16 +89,17 @@ with:
#### Case 2 - Where the user would want to re-evaluate the key
```yaml
uses: actions/cache/save@v4
uses: danySam/gcs-cache/save@v1
with:
key: npm-cache-${{hashfiles(package-lock.json)}}
gcs-bucket: my-github-cache-bucket
```
### Always save cache
There are instances where some flaky test cases would fail the entire workflow and users would get frustrated because the builds would run for hours and the cache couldn't be saved as the workflow failed in between.
For such use-cases, users now have the ability to use the `actions/cache/save` action to save the cache by using an [`always()`](https://docs.github.com/actions/writing-workflows/choosing-what-your-workflow-does/expressions#always) condition.
This way the cache will always be saved if generated, or a warning will be generated that nothing is found on the cache path. Users can also use the `if` condition to only execute the `actions/cache/save` action depending on the output of previous steps. This way they get more control of when to save the cache.
For such use-cases, users now have the ability to use the `danySam/gcs-cache/save` action to save the cache by using an [`always()`](https://docs.github.com/actions/writing-workflows/choosing-what-your-workflow-does/expressions#always) condition.
This way the cache will always be saved if generated, or a warning will be generated that nothing is found on the cache path. Users can also use the `if` condition to only execute the `danySam/gcs-cache/save` action depending on the output of previous steps. This way they get more control of when to save the cache.
To avoid saving a cache that already exists, the `cache-hit` output from a restore step should be checked.
@ -95,19 +122,20 @@ jobs:
- name: Restore cached Prime Numbers
id: cache-prime-numbers-restore
uses: actions/cache/restore@v4
uses: danySam/gcs-cache/restore@v1
with:
key: ${{ runner.os }}-prime-numbers
path: |
path/to/dependencies
some/other/dependencies
gcs-bucket: my-github-cache-bucket
# Intermediate workflow steps
- name: Always Save Prime Numbers
id: cache-prime-numbers-save
if: always() && steps.cache-prime-numbers-restore.outputs.cache-hit != 'true'
uses: actions/cache/save@v4
uses: danySam/gcs-cache/save@v1
with:
key: ${{ steps.cache-prime-numbers-restore.outputs.cache-primary-key }}
path: |