Upgrading
This page gives the notes that you must read before you upgrade from one v1 release to a later one. The newest release is first. The Changelog lists every change in every release.
uses: xSAVIKx/cloud-cache-action@v1 always gets the newest v1 release. To stay on one release, pin the action to a full tag, such as @v1.10.1, or to a commit SHA.
v1.8 and later
There are no breaking changes and no default changes in v1.8, v1.9 and v1.10.
- v1.8, unsigned upload payloads. Uploads over
https://sendx-amz-content-sha256: UNSIGNED-PAYLOAD. When a server refuses the header, the action sends the request again with a signed payload and logs one line. SetCLOUD_CACHE_UNSIGNED_PAYLOAD=falsein the job environment to turn the change off. - v1.9, AWS buckets with Object Lock. Uploads to AWS S3 no longer send an SDK checksum for each part. An AWS bucket with an Object Lock default retention requires a checksum on each upload, so a save to it fails with
400 InvalidRequest. SetCLOUD_CACHE_SDK_CHECKSUMS=truein the job environment to send the SDK checksums again. - v1.9,
transfer-tuning. The newtransfer-tuninginput has the defaultfixed, so a workflow that does not set it behaves as before. See Automatic tuning.
v1.7
There are no breaking changes in the inputs of v1.7, but one default changes. Caches saved by v1.1 to v1.6 restore normally.
ACTIONS_CACHE_MODE: the S3 tier now obeys this variable, asactions/cachedoes. When a workflow does not set thecache-modekey, GitHub setsreadforpull_request_target,issue_commentandworkflow_run. An S3-only job on one of these triggers then restores but does not save. To save again, setcache-mode: writeon the job. Do this only when the job cannot run untrusted code. See Parity with actions/cache.- Prune:
older-than-daysis now optional. The step fails only when none of the four rule inputs is set, so an existing prune step works as before.
v1.6
There are no breaking changes in v1.6. Caches saved by v1.1 to v1.5 stay valid. A streamed save now stores its checksum as an object tag. Grant s3:PutObjectTagging and s3:GetObjectTagging to the cache credentials. See How Caches Are Stored and the Security guide.
v1.5
There are no breaking changes in v1.5, and no default changes. It adds RustFS as a provider preset. Every other workflow behaves exactly as it did in v1.4.
v1.4
There are no breaking changes in v1.4. Caches saved by earlier versions restore normally. One default changes:
- Parallel transfers follow the
actions/cachedefaults. Restores of archives larger than 8 MiB download in 8 concurrent ranged parts, controlled by the newdownload-concurrency(default8) anddownload-chunk-size(default8388608) inputs; setdownload-concurrency: 1to keep the single-request download of v1.3. Saves send 8 parts at once instead of 4, controlled by the newupload-concurrencyinput, and the defaultupload-chunk-sizeis now 64 MiB instead of 10 MiB, so a save may hold up to 512 MiB of parts in memory; setupload-concurrency: 4andupload-chunk-size: 10485760to keep the v1.3 footprint.
v1.3
There are no breaking changes in v1.3. Caches saved by v1.1 and v1.2 restore normally, the key layout, ${version} hashing and archive format are unchanged, and a save that sets none of the new inputs writes the same object as v1.2 did. Every addition is opt-in:
- Object metadata and tags via the new
metadataandtagsinputs, with the restored object's metadata exposed as the newcache-metadataoutput ({}when there is none, on a GitHub-tier hit, or withlookup-only: true). Both are best-effort extras that never fail a save. - Inspecting a cache lookup: the new
explaininput (defaultfalse) and the newinspectsub-action, neither of which changes what a restore does. - Metrics and timings: the new
cache-restore-duration-ms,cache-save-duration-ms,cache-transfer-duration-msandcache-bytesoutputs, set on every path, and the newmetrics-fileinput (default"", which keeps the previous file-free behavior). - Streaming saves now carry a checksum. A
streaming: truesave attachescloud-cache-sha256after the upload, so streamed archives are integrity-checked on restore like file-mode ones. See Streaming Archives.
v1.2
There are no breaking changes in v1.2. Caches saved by v1.1 remain valid and continue to restore normally; objects saved without a sha256 checksum (any v1.1 cache) simply skip the new integrity check.
- New, all opt-in or on-by-default without changing existing behavior: Cache Pruning (a new
prunesub-action, run separately — nothing changes for existingrestore/savesteps), Archive Integrity (automatic; only skips when a checksum is absent), Safe Concurrent Saves (automatic; falls back cleanly on servers that reject the condition), Job Summary (on by default — setjob-summary: falseto keep the old, summary-free behavior), and Streaming Archives (opt-in viastreaming: true; defaultfalsekeeps the v1.1 file-based path). - Windows symlinks are now covered by the Windows CI round trip: they restore as native symlinks through Git's GNU
tarwithMSYS=winsymlinks:nativestrict, as in v1.1. - Tag-triggered runs: if a run started by pushing a tag is the only place that saves a given cache, no pull request or branch build will ever restore it — restores never search
refs/tags/*. Save on the default branch instead (apushthere, orworkflow_dispatch), or see Tag-triggered runs and refs for usingscoped-to-ref: false. - Maintenance: Dependabot now keeps npm and GitHub Actions dependencies up to date, and publishing a GitHub release runs
.github/workflows/release.ymlautomatically — see Releasing.
v1.1
v1.1 changes how cache objects are named, so caches saved by v1.0 are not found and are rebuilt once.
- Key layout: object keys now include the Git ref and a cache version:
${GITHUB_REPOSITORY}/${prefix}${ref}/${key}/${version}/${archive_filename}. The version hashespath, the compression method and, on Windows,enableCrossOsArchive, so a cache is never restored into a job that caches different paths. - Paths:
pathsupports globs,~and!exclusions like actions/cache, and archives store paths relative toGITHUB_WORKSPACE. See Paths and exclusions. - Branch isolation: restores search the current ref, then the pull request base branch, then the default branch. Set
scoped-to-ref: falseto share caches across all refs. save-alwayswas removed.dual-cache-strategy: independentnow behaves asbackfilland logs a warning.dual-cache-strict: truenow fails the step on any tier error during restore or save.
The action never reads v1.0 objects again; let a bucket lifecycle rule expire them.
Ref scoping stores a separate cache for every branch and pull request merge ref (refs/pull/<n>/merge), so the bucket grows with the number of active refs. A lifecycle rule that expires old cache objects is strongly recommended. Add an AbortIncompleteMultipartUpload rule as well (for example, after 1 day): the action aborts the multipart uploads it sees fail, but a job that is cancelled or whose runner dies mid-upload leaves its uploaded parts behind, stored and billed until such a rule removes them.