@actions/cache Package Deprecation Notice. Upgrade to the latest 4.0.0 or higher before February 1st 2025

[Link-]

TLDR; The cache backend service has been rewritten from the ground up for improved performance and reliability. The @actions/cache package now integrates with the new cache service (v2) APIs.

The new service will gradually roll out as of February 1st, 2025. The legacy service will also be sunset on the same date. Changes in this release are fully backward compatible.

All previous versions of this package will be deprecated. We recommend upgrading to version 4.0.0 or higher as soon as possible before February 1st, 2025.

If you do not upgrade, all workflow runs using any of the deprecated @actions/cache packages will fail.

Upgrading to the recommended version should not break or require any changes to your workflows beyond updating your package.json to version 4.0.0 or higher.

Context

The cache backend service has been rewritten from the ground up for improved performance and reliability. In version 4.0.0 of the @actions/cache package, we introduced a more consistent API contract with the cache backend service.

The new service will decrease the cache upload duration by up to ~80% when using GitHub Hosted Runners. The cache download performance will be the same. If you’re using self-hosted runners the upload duration is expected to improve, or in the worst-case stay the same. Cache upload/download performance depends on your network topology, hardware and geographical region used for hosting among other factors.

We will start rolling out the new backend service gradually as of February 1st, 2025. We will issue further guidance as we approach this deadline.

The legacy backend service will be sunset shortly after February 1st, 2025. We will not support both services at the same time. Refer to the migration guide below for further information on how to prevent disruption to your teams.

Migration guide

How to upgrade

The new changes to the @actions/cache package should be seamless and fully backward compatible. You are not expected to change anything in your code to use the new service.

In order to upgrade, simply bump up the version of @actions/cache in your package.json to 4.0.0 (or above). We will be releasing bug fixes and improvements throughout the period leading to February 1st, 2025.

Here is a sample package.json for your reference.

{
  "name": "my-github-action",
  "version": "1.0.0",
  "description": "A GitHub Action using @actions/cache",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [
    "github",
    "actions",
    "cache"
  ],
  "author": "Your Name",
  "license": "MIT",
  "dependencies": {
    "@actions/cache": "^4.0.0"
  }
}

Maintainers of solutions that depend on @actions/cache

Please upgrade the @actions/cache package to 4.0.0 or higher and release new versions of your solutions as soon as possible.

The API changes are backward compatible and enabled via feature flags to facilitate the gradual & safe rollout of the new service.

If you are a maintainer of any setup-* action, please comment on this discussion and we will look into enabling the new service for you on a test repository, so that you can test the change before it's rolled out globally.

All of the previously released versions in the list below are now deprecated:

Deprecated versions	Release Date
3.3.0	latest
3.2.4	10 months ago
3.2.3	a year ago
3.2.2	a year ago
3.2.1	2 years ago
3.2.0	2 years ago
3.1.4	2 years ago
3.1.3	2 years ago
3.1.2	2 years ago
3.1.1	2 years ago
3.1.0	2 years ago
3.1.0-beta.3	2 years ago
3.1.0-beta.2	2 years ago
3.1.0-beta.1	2 years ago
3.0.6	2 years ago
3.0.5	2 years ago
3.0.4	2 years ago
3.0.3	2 years ago
3.0.2	2 years ago
3.0.1	2 years ago
3.0.0	2 years ago
2.0.6	2 years ago
2.0.5	3 years ago
2.0.4	3 years ago
2.0.3	3 years ago
2.0.2	3 years ago
2.0.1	3 years ago
2.0.0	3 years ago
1.0.11	3 years ago
1.0.10	3 years ago
1.0.9	3 years ago
1.0.8	3 years ago
1.0.7	4 years ago
1.0.6	4 years ago
1.0.5	4 years ago
1.0.4	4 years ago
1.0.3	4 years ago
1.0.2	4 years ago
1.0.1	4 years ago
1.0.0	4 years ago
1.2.1	5 years ago
0.2.0	5 years ago
0.1.0	5 years ago

GitHub Enterprise Server

This deprecation will not impact any existing versions of GitHub Enterprise Server that are currently in use.

[crohr]

@Link- Can I put a request to keep the fallback mechanism for save/restore V1 in

toolkit/packages/cache/src/cache.ts

Lines 73 to 104 in b7a00a3

	export async function restoreCache(
	paths: string[],
	primaryKey: string,
	restoreKeys?: string[],
	options?: DownloadOptions,
	enableCrossOsArchive = false
	): Promise<string | undefined> {
	const cacheServiceVersion: string = getCacheServiceVersion()
	core.debug(`Cache service version: ${cacheServiceVersion}`)
	checkPaths(paths)
	switch (cacheServiceVersion) {
	case 'v2':
	return await restoreCacheV2(
	paths,
	primaryKey,
	restoreKeys,
	options,
	enableCrossOsArchive
	)
	case 'v1':
	default:
	return await restoreCacheV1(
	paths,
	primaryKey,
	restoreKeys,
	options,
	enableCrossOsArchive
	)
	}
	}

even after the v1 cache backend has been deprovisioned?

This is used in quite a few places to transparently replace the Azure backend with another one (overriding the ACTIONS_CACHE_URL env variable). For instance:

• https://github.com/falcondev-oss/github-actions-cache-server
• https://depot.dev/blog/github-actions-cache
• (soon) https://runs-on.com

With v2, the calls go directly through the azure blob sdk, which would be harder to replace.

[Link-]

@crohr - I understand your use case, but I'm afraid this is not a path we would like to support. By going down this path we'll be taking on unnecessary technical debt and increase the maintenance cost of this action and the cache package.

If you want to use your own backend for caching purposes, you're better off forking this action instead!

Granted, the long tail until the fallback to v1 is removed will be long, but I'm afraid we will not be making any promises to keep it indefinitely.

[crohr]

@Link- thanks, understood. Would it be possible for you to enable the V2 cache on the runs-on/test-cache-v2 repository so that I can test the changes?

[Link-]

As of January 2025, we will

[MikeMcC399]

Updating to @actions/cache@4 introduces the use of dependencies which are deprecated. This is less than ideal.

• See @actions/[email protected] triggers SNYK-JS-INFLIGHT-6095116 vulnerability warning #1901

twirp-ts is apparently unmaintained

[Link-]

Thank you @MikeMcC399 - yes, that's a fair analysis. This is a dependency that needs to be revisited for both cache and artifacts. I'll add it to our backlog to address in the next minor release.

[MikeMcC399]

I much appreciate your response @Link- !

Although CI tests are running fine, we'll be hanging back on upgrading in the meantime, unless we're forced to.