Time sensitive: GitHub Actions cache service shutdown

[Link-]

The actions/cache backend service has been rewritten from the ground up for improved performance and reliability. The new service has been gradually rolling out since February 1st, 2025. The legacy service will be sunset by April 15th 2025.

We have identified that this project is integrating with the legacy cache service without using the official and supported package. Unfortunately, that means that you have to introduce code changes in order to be compatible with the new service we're rolling out.

The new service uses an entirely new set of internal API endpoints. To help with your changes we have provided the proto definitions below to help generate compatible clients to speed up your migration.

These internal APIs were never intended for consumption the way your project is at the moment. Since this is not a paved path we endorse, it's possible there will be breaking changes in the future. We are reaching out as a courtesy because we do not wish to break the workflows dependent on this project.

Please introduce the necessary changes ASAP. Otherwise, storing and retrieving cache entries will start to fail. There will be no need to offer backward compatibility as the new service has been rolled out to all repositories.

The cutover point in time will be the moment the new service is rolled out to a given repository. Then, users will no longer have access to cache entries from the legacy service and are expected to store / retrieve cache entries from the new service.

Expand for proto definitions

cache.proto

syntax = "proto3";

import "cachemetadata.proto";

package v1;

service CacheService {
    // Generates a SAS URL with write permissions to upload a cache archive
    rpc CreateCacheEntry(CreateCacheEntryRequest) returns (CreateCacheEntryResponse);
    // Indicate the completion of a cache archive upload. Triggers post-upload processing
    rpc FinalizeCacheEntryUpload(FinalizeCacheEntryUploadRequest) returns (FinalizeCacheEntryUploadResponse);
    // Generates a SAS URL with read permissions to download a cache archive
    rpc GetCacheEntryDownloadURL(GetCacheEntryDownloadURLRequest) returns (GetCacheEntryDownloadURLResponse);
}

message CreateCacheEntryRequest {
    // Scope and other metadata for the cache entry
    results.entities.v1.CacheMetadata metadata = 1;
    // An explicit key for a cache entry 
    string key = 2;
    // Hash of the compression tool, runner OS and paths cached
    string version = 3;
}

message CreateCacheEntryResponse {
    bool ok = 1;
    // SAS URL to upload the cache archive
    string signed_upload_url = 2;
}

message FinalizeCacheEntryUploadRequest {
    // Scope and other metadata for the cache entry 
    results.entities.v1.CacheMetadata metadata = 1;
    // An explicit key for a cache entry
    string key = 2;
    // Size of the cache archive in Bytes
    int64 size_bytes = 3;
    // Hash of the compression tool, runner OS and paths cached
    string version = 4;
}

message FinalizeCacheEntryUploadResponse {
    bool ok = 1;
    // Cache entry database ID
    int64 entry_id = 2;
}

message GetCacheEntryDownloadURLRequest {
    // Scope and other metadata for the cache entry 
    results.entities.v1.CacheMetadata metadata = 1;
    // An explicit key for a cache entry
    string key = 2;
    // Restore keys used for prefix searching
    repeated string restore_keys = 3;
    // Hash of the compression tool, runner OS and paths cached
    string version = 4;
}

message GetCacheEntryDownloadURLResponse {
    bool ok = 1;
    // SAS URL to download the cache archive
    string signed_download_url = 2;
    // Key or restore key that matches the lookup
    string matched_key = 3;
}

cachemetadata.proto

syntax = "proto3";

import "cachescope.proto";

package v1;

message CacheMetadata {
    // Backend repository id
    int64 repository_id = 1;
    // Scopes for the cache entry 
    repeated CacheScope scope = 2;
}

cachescope.proto

syntax = "proto3";

package v1;

message CacheScope {
    // Determines the scope of the cache entry
    string scope = 1;
    // None: 0 | Read: 1 | Write: 2 | All: (1|2)
    int64 permission = 2;
}

Further information

• Deprecation Notice - Upgrade to latest before February 1st 2025 actions/cache#1510
• @actions/cache Package Deprecation Notice. Upgrade to the latest `4.0.0` or higher before February 1st 2025 actions/toolkit#1890

Link to changelog posts

• https://gh.io/gha-cache-sunset
• https://github.blog/changelog/2025-01-15-github-actions-ubuntu-20-runner-image-brownout-dates-and-other-breaking-changes/
• https://github.blog/changelog/2024-12-05-notice-of-upcoming-releases-and-breaking-changes-for-github-actions/
• https://github.blog/changelog/2024-09-16-notice-of-upcoming-deprecations-and-changes-in-github-actions-services/

[Yash123-DEV]

can i contribute

[bennypowers]

we're encountering this with increasing frequency e.g. https://github.com/RedHat-UX/red-hat-design-system/actions/runs/14338164123/job/40192290168

[aomarks]

I've got a fix in the works, should be out this week.

Sorry for the slow response.

[aomarks]

Wireit 0.14.12 was just released, which upgrades to the V2 caching API.

Most users only need to update their wireit dependency to get this fix. The setup-github-actions-caching action was also updated, but if using the recommended - uses: google/wireit@setup-github-actions-caching/v2 clause, that will get picked up automatically. If using a more granular/pinned version for the action, then it should be updated to v2.0.3 (#f21db1f3a6a4db31f42787a958cf2a18308effed).

---

Thank you very much @Link- for the heads-up, and sharing the proto definitions is greatly appreciated!

For background: I would have liked to use the official @actions/cache client library instead of rolling our own, however the primary reason I chose not to is that the official library would increase our install size from 2.4MB to 86MB, and our number of transitive dependencies from 31 to 113. The secondary reason was that the official client library doesn't give full control over the cache keys (IIRC it couples the key to the file paths being cached).