Magic Nix Cache

The gha-cache crate provides an asynchronous API to the GitHub Actions Cache (GHAC) service. It allows you to upload binary blobs using AsyncRead streams and obtain presigned URLs to download them.

GHAC identifies blobs using a 3-tuple:

• Cache Key: A developer-specified name.
• Cache Version: A string acting as a namespace (e.g., a SHA256 hash of paths/compression). This crate allows users to provide arbitrary bytes to mutate this hash.
• Cache Scope: The branch containing the workflow run that uploaded the blob.

The gha-cache crate specifically supports the GitHub Actions Cache API (the private API used by GHAC), rather than the public GitHub REST API.

To use this crate, you must provide credentials for the following endpoints:

• Endpoint: $ACTIONS_CACHE_URL
• Token: $ACTIONS_RUNTIME_TOKEN

Note: This crate does not currently support the GitHub REST API (used for listing and deleting blobs via $GITHUB_API_URL).

Because GHAC uses private APIs requiring special tokens, you must retrieve them from a workflow run. The recommended method is using the keygen workflow provided in this repository:

1. Generate an age encryption key:

   nix shell nixpkgs#age --command age-keygen -o key.txt

2. Add the Public Key from that file as a repository secret named AGE_PUBLIC_KEY.
3. Trigger the keygen workflow in your repository.
4. The workflow will output a command that allows you to decrypt the necessary credentials.

To use Magic Nix Cache, add the DeterminateSystems/magic-nix-cache-action@main to your GitHub Actions workflow after installing Nix. This provides a zero-configuration binary cache that uses GitHub Actions' built-in cache to share builds between workflow runs.

Important: You must ensure your job has the necessary permissions for the GitHub Actions cache to work, specifically id-token: write.

permissions:
  contents: read
  id-token: write
steps:
  - uses: actions/checkout@v4
  - uses: DeterminateSystems/nix-installer-action@main
  - uses: DeterminateSystems/magic-nix-cache-action@main
  - run: nix flake check

Nix binary cache manifests (typically found in .narinfo files or /nix-cache-info) use a simple, flat key-value format where a colon (:) acts as the delimiter. The format is not strictly defined by a formal specification, and official Nix implementations often handle serialization manually.

Example of a /nix-cache-info file:

StoreDir: /nix/store
WantMassQuery: 1
Priority: 40

FlakeHub authentication can be sourced in two ways:

1. Determinate Nixd: If determinate-nixd is available (detected via the presence of the determinate-nixd.socket at /nix/var/determinate/determinate-nixd.socket), the cache will automatically use the netrc file located at /nix/var/determinate/netrc.
2. Manual Netrc: If determinate-nixd is missing, you must provide a path to a netrc file using the --flakehub-api-server-netrc <PATH> flag.

The client includes a built-in circuit breaker to protect against GitHub Actions rate limiting (HTTP 429) or service overloads (502 Bad Gateway / Resource Exhausted).

When the client detects these errors, it trips the circuit breaker and executes the provided CircuitBreakerTrippedCallback. Once tripped, subsequent calls to upload_file or get_file_url will immediately return Error::CircuitBreakerTripped without making network requests.

You can check the current status using circuit_breaker_tripped().

The fingerprint is a specific string format used to identify a NAR info object. It is used for authentication and identification in Nix manifests. The format is a semicolon-delimited string containing the store path, NAR hash, NAR size, and a comma-delimited list of references.

Format: 1;{storePath};{narHash};{narSize};{commaDelimitedReferences}

The --use-gha-cache and --use-flakehub flags use a ternary logic system to determine cache preference:

• No value provided: NoPreference. The application will attempt to enable the cache if appropriate (e.g., if determinate-nixd is available for FlakeHub).
• --use-gha-cache (or --use-flakehub): Disabled. The cache is explicitly turned off.
• --use-gha-cache=enabled (or --use-flakehub=enabled): Enabled. The cache is explicitly turned on.

This is a complete example of a Linux or macOS workflow configured to use Magic Nix Cache. It includes the required permissions and the sequence of steps to check out code, install Nix, initialize the cache, and run a Nix command.

name: CI

on:
  push:
  pull_request:

jobs:
  check:
    runs-on: ubuntu-22.04
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - uses: DeterminateSystems/nix-installer-action@main
      - uses: DeterminateSystems/magic-nix-cache-action@main
      - run: nix flake check