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/

[Xuanwo]

Thank you @Link- for informing us. We will evaluate and implement the necessary changes.

[Xuanwo]

By the way @Link- we have received a report like this: #5583, which may be related to the action service on GHES with AWS S3. Will the new implementation address this issue?

[Link-]

@Xuanwo At the moment GHES is not affected by this change.

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. 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

---

By the way @Link- we have received a report like this: #5583, which may be related to the action service on GHES with AWS S3. Will the new implementation address this issue?

We need to investigate this on our end for the legacy service. It'd be great to receive a support ticket for this issue as you've suggested in the discussion already so that we can track the work.

[DLukeNelson]

@Link-
I have previously opened up this discussion to attempt to understand my issue a little better.

[Link-]

Thanks @DLukeNelson - As I noted in the body of the main issue, direct integration with the cache service by not using @actions/cache is currently not a supported path. Even if the technical fix is not complex, I'm afraid there's very little support we can offer for this at the moment. We're discussing internally whether we make a public API available for the cache service, but that is still in the early stages and I don't have much to say about it at this point.

[Xuanwo]

Some notes for this service migrate:

• GHAC v2 is a twirp based services that users need to talk to {base_url}/twirp/{method}.
• GHAC v2 requires the Azure SDK for uploading (luckily, OpenDAL has native Azure support).
• GetCacheEntryDownloadURL may returns empty signed_download_url to indicate the cache entry doesn't exist. But the cache itself no longer seems consistent, which means that reading after writing could also fail.