DeterminateSystems
Time sensitive: GitHub Actions cache service integration
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
- https://github.com/actions/cache/discussions/1510
- https://github.com/actions/toolkit/discussions/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/
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
opendal has added support for cache v2: https://github.com/apache/opendal/releases/tag/v0.52.0
error: unable to download 'http://127.0.0.1:37515/01x5k4nlxcpyd85nnr0b9gm89rm8ff4x.narinfo': HTTP error 418
response body:
GitHub API error: API error (422 Unprocessable Entity): StructuredApiError { message: "This legacy service is shutting down, effective April 15, 2025. Migrate to the new service ASAP. For more information: https://gh.io/gha-cache-sunset" }
at magic-nix-cache/src/gha.rs:150
2025-04-16T01:13:19.186562Z ERROR magic_nix_cache::gha: Upload of path '/nix/store/iv9jfm7scprsvax6kzjr3flm09pak7kc-libXft-2.3.8' failed: GitHub API error: API error (422 Unprocessable Entity): StructuredApiError { message: "This legacy service is shutting down, effective April 15, 2025. Migrate to the new service ASAP. For more information: https://gh.io/gha-cache-sunset" }
at magic-nix-cache/src/gha.rs:150
2025-04-16T01:13:19.258518Z ERROR magic_nix_cache::gha: Upload of path '/nix/store/iwlabmwfw8shz7kh4kara81gmmicq9pk-json-c-0.18' failed: GitHub API error: API error (422 Unprocessable Entity): StructuredApiError { message: "This legacy service is shutting down, effective April 15, 2025. Migrate to the new service ASAP. For more information: https://gh.io/gha-cache-sunset" }
at magic-nix-cache/src/gha.rs:150
"This legacy service is shutting down, effective April 15, 2025."
Props to GitHub for being punctual I guess?
I use this for a lot of my personal projects. I didn't notice this problem in time to actually do anything about it and now the service times out, which causes GitHub Actions to hang for ~6 hours while magic-nix-cache retries in vein. So uh, I finally noticed.
Anyway, I implemented the new cache API in https://github.com/DeterminateSystems/magic-nix-cache/pull/139. Zero clue how likely it is that this will be accepted given the blog post, but may as well throw it out there.
If you want to try it out, do so at your own risk and remember not to trust binaries from random people on the Internet with sensitive data. Anyway though, my test build is over here and you can try it like this:
...
- uses: DeterminateSystems/nix-installer-action@v17
- uses: DeterminateSystems/magic-nix-cache-action@main
with:
source-url: https://github.com/jchw-forks/magic-nix-cache/releases/download/nightly/magic-nix-cache-X64-Linux
...
(Just switch the source-url for whatever CPU architecture/OS you're running on. See the release page.)
Thanks for all the effort!
I'm confused. There are two repositories:
- magic-nix-cache-action
- magic-nix-cache
And there's flakehub-cache-action as well.
🤷
help?
This (magic-nix-cache) is the Rust source code for the daemon that acts as a caching proxy. magic-nix-cache-action is the GitHub action, that glues it into GitHub Actions workflows. flakehub-cache-action isn't really related, it is an alternative to Magic Nix Cache where the cache is also usable outside of CI (e.g. you can reuse the cache on your local machine too) and has less limitations, using FlakeHub.
You want to use magic-nix-cache-action in your GitHub workflows, at v10 (current release.) or main.
I'm not sure if this pulls the latest magic-nix-cache binary yet. I think it will, but if not, you can override the source parameters, e.g. you can pass source-tag to the latest release tag on this repo, the same way I'm showing how to override source-url above in my snippet:
...
- uses: DeterminateSystems/magic-nix-cache-action@v10
with:
source-tag: v0.1.5
...
However, I think this shouldn't be needed. you should just be able to do:
...
- uses: DeterminateSystems/magic-nix-cache-action@v10
...
..And if it works and doesn't seem to fail indefinitely you should be good to go.
I haven't had a chance to test since the releases were made, so I apologize if I have any of this wrong.
Thank you for the exaplanation. I wish the readmes made all this clear and did not instruct to use an unrelated flakehub-cache-action.
Yeah, that’s on me. I have an open ticket (and PR) to clean this up. Give us a few days please 😅
On Fri, Jun 13, 2025, at 11:35 PM, mightyiam wrote:
mightyiam left a comment (DeterminateSystems/magic-nix-cache#123) https://github.com/DeterminateSystems/magic-nix-cache/issues/123#issuecomment-2972213013 Thank you for the exaplanation. I wish the readmes made all this clear and did not instruct to use an unrelated flakehub-cache-action.
— Reply to this email directly, view it on GitHub https://github.com/DeterminateSystems/magic-nix-cache/issues/123#issuecomment-2972213013, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAASXLCJEB2ZFFO5ZIAS2733DOJ7FAVCNFSM6AAAAABW57V64OVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDSNZSGIYTGMBRGM. You are receiving this because you were mentioned.Message ID: @.***>
