Time sensitive: GitHub Actions cache service integration

[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 March 1st.

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 before the end of February. Otherwise, storing and retrieving cache entries will start to fail. There will be no need to offer backward compatibility as the new service will be rolled out to all repositories by February 13th 2025.

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://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/

[Link-]

There will be no need to offer backward compatibility as the new service will be rolled out to all repositories by February 13th 2025.

I'm afraid this statement is wrong, it's an oversight on my end. You need to keep the old client if you want to maintain compatibility with GHES. Only use the new client if the following conditions are fulfilled:

https://github.com/actions/toolkit/blob/340a6b15b5879eefe1412ee6c8606978b091d3e8/packages/cache/src/internal/config.ts#L14