Skip to content

Inputs and Outputs ​

This page lists the inputs and the outputs of the main action, xSAVIKx/cloud-cache-action@v1. The restore and save sub-actions take the same inputs, with these exceptions:

  • restore does not take the save inputs: read-only, compression-level, upload-chunk-size, upload-concurrency, metadata and tags.
  • save does not take the restore inputs: restore-keys, lookup-only, fail-on-cache-miss, read-only, restore-priority, explain, download-concurrency and download-chunk-size.

The prune and inspect sub-actions have their own inputs and outputs, on their own pages. The action.yml file of each action is the full definition (see Action Metadata Definitions).

Sub-actions ​

ActionUse
xSAVIKx/cloud-cache-action@v1Restores in the main step and saves in the post step, as actions/cache does.
xSAVIKx/cloud-cache-action/restore@v1Restores only.
xSAVIKx/cloud-cache-action/save@v1Saves only. Use it with if: always() to save after a failed step (see Saving after failed steps).
xSAVIKx/cloud-cache-action/prune@v1Deletes old cache archives, for example on a schedule. See Pruning Caches.
xSAVIKx/cloud-cache-action/inspect@v1Reports which object a restore would use, and why, without a restore. See Inspecting Lookups.

Inputs ​

InputDescriptionRequiredDefault
bucketName of the S3 bucketYes—
keyExplicit key for restoring and saving cacheYes, unless preset is set—
pathMultiline list of paths, globs and ! exclusions to cache (see Paths and exclusions)Yes, unless preset is set—
presetPackage manager preset that gives the default path, key and restore-keys: npm, yarn, pnpm, bun, pip, poetry, uv, gradle, maven, cargo, go (see Cache presets)No—
restore-keysMultiline string of prefix keys for fallback matchingNo—
endpointCustom S3 endpoint URLNoAuto/AWS
regionAWS or S3 provider regionNoAuto/us-east-1
providerPreset: aws, r2, gcs, b2, fastly, garage, seaweedfs, minio, rustfsNoAuto
access-key / accessKeyS3 Access Key IDNoAWS_ACCESS_KEY_ID
secret-key / secretKeyS3 Secret Access KeyNoAWS_SECRET_ACCESS_KEY
session-token / sessionTokenS3 Session TokenNoAWS_SESSION_TOKEN
force-path-styleForce path-style S3 URLsNoAuto
prefixSubfolder prefix path inside bucketNo""
s3-key-patternCustom S3 key template pattern (supports ${ENV_VARS})NoSee below the table
scoped-to-repositoryPrefix bucket cache paths with repository nameNotrue
scoped-to-refRestore from the current ref, then the PR base, then the default branch; false shares caches across refsNotrue
lookup-onlyCheck existence without downloadingNofalse
fail-on-cache-missFail workflow if cache is not foundNofalse
enableCrossOsArchiveAllow Windows runners to save/restore cross-OS cachesNofalse
read-onlyRestore cache but never save in post stepNofalse
retryEnable exponential backoff retries on S3 operationsNotrue
retry-countMaximum number of S3 retriesNo3
use-fallbackFallback to GitHub Actions cache service if S3 failsNofalse
dual-cacheCache to both S3 and GitHub Actions Cache simultaneouslyNofalse
restore-priorityCache source to query first: s3-first or github-firstNos3-first
dual-cache-strategybackfill (upload to a tier only if it lacks the key) or skip-on-hitNobackfill
dual-cache-strictFail the step when either tier errors during restore or saveNofalse
streamingStream archives directly between tar and S3 without a temporary file (experimental; see Streaming Archives)Nofalse
download-concurrencyRanged GET requests a restore runs at once for archives larger than download-chunk-size (1–32); 1 downloads in one request (see Parallel Transfers)No8
download-chunk-sizeBytes per ranged GET request (1 MiB–128 MiB); archives no larger than this use one requestNo8388608
upload-concurrencyMultipart upload parts sent at once (1–32)No8
upload-chunk-sizeBytes per multipart upload part (5 MiB–128 MiB); the same input actions/cache takesNo67108864
transfer-tuningauto selects the part size and the concurrency per archive from its size (and, for a save, the provider); a transfer input you set still wins (see Parallel Transfers)Nofixed
compression-levelzstd 1–19 or gzip 1–9 for saving; lower is faster and larger (see Performance)NoTool default
job-summaryWrite a job summary table with the cache keys, hit, source, size and durationNotrue
metadataUser metadata (x-amz-meta-*) for every saved object, one key=value per line, with surrounding whitespace trimmed (see Object Metadata and Tags)No—
tagsObject tags for every saved object, one key=value per line (up to 10; up to 9 with streaming: true, which reserves one slot for the checksum tag)No—
explainLog why the lookup hits or misses before restoring (see Inspecting a cache lookup)Nofalse
metrics-fileAppend one JSON line of timings and sizes for this step to this file, relative to the workspaceNo""

The default of s3-key-pattern is:

text
${GITHUB_REPOSITORY}/${prefix}${ref}/${key}/${version}/${archive_filename}

For the rules that path follows (globs, ~, ! exclusions and symbolic links), see Paths and Exclusions.

Outputs ​

  • cache-hit: 'true' if an exact match was found for the primary key; 'false' otherwise.
  • cache-primary-key: The evaluated primary cache key.
  • cache-matched-key: Key that was matched and restored.
  • cache-size: Archive size in bytes.
  • cache-storage-provider: Resolved storage provider (e.g. r2, gcs, aws).
  • cache-s3-key: Full S3 object key inside the bucket.
  • cache-etag: ETag checksum of the archive in S3.
  • cache-metadata: JSON object of the restored object's user metadata, excluding cloud-cache-* keys; {} when there is none, on a GitHub-tier hit, or with lookup-only: true, which never downloads the object.
  • cache-hit-source: The tier that serviced the hit: s3, github, or none.
  • cache-saved-sources: Tiers successfully saved to: s3, github, or s3,github.
  • cache-restore-duration-ms: Wall-clock milliseconds the restore step took; 0 when it did not complete.
  • cache-save-duration-ms: Wall-clock milliseconds the save step took; 0 when it did not complete.
  • cache-transfer-duration-ms: Milliseconds spent on the S3 download or upload alone; 0 when nothing was transferred.
  • cache-bytes: Size in bytes of the archive restored or saved; 0 when none was. See Metrics and Timings.