️❄️ FlakeHub Cache Action

FlakeHub Cache is the zero-configuration binary cache for GitHub Actions, workstations, production, and other CI platforms.

FlakeHub Cache is part of Determinate, the best way to use Nix on macOS, WSL, and Linux. It is an end-to-end toolchain for using Nix, from installation to collaboration to deployment.

Based on the Determinate Nix Installer and its corresponding Nix Installer Action, responsible for over tens of thousands of Nix installs daily.

🫶 Platform support

• Automatic, authenticated integration with GitHub Actions
• Cached paths are available on developer and target machines
• Fully managed by Determinate Systems
• 🐧 Linux, x86_64, aarch64
• 🍏 macOS, x86_64 and aarch64
• 🪟 WSL2, x86_64 and aarch64
• 🐋 Containers, ARC, and Act
• 🐙 GitHub Enterprise Server
• 💁 GitHub Hosted, self-hosted, and long running Actions Runners

️🔧 Usage

Here's an example Actions workflow configuration that uses flakehub-cache-action:

name: CI

on:
  pull_request:
  push:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    permissions:
      id-token: "write"
      contents: "read"
    steps:
      - uses: actions/[email protected]
      - uses: DeterminateSystems/determinate-nix-action@v3
      - uses: DeterminateSystems/flakehub-cache-action@v2 # or v2.1 to pin to a release
      - run: nix build .

Important

You must add a permissions block like the one in the example above or else Determinate Nix can't authenticate with FlakeHub or FlakeHub Cache.

📌 Version pinning: lock it down!

Why pin your Action?

Unlike DeterminateSystems/magic-nix-cache-action, we fully support explicit version pinning for maximum consistency. This Action is automatically tagged for every release, giving you complete control over your CI environment:

📍 Pinning to DeterminateSystems/[email protected] guarantees:

• Same flakehub-cache-action revision every time
• Reproducible CI workflows, even years later

✨ Using @main instead? You'll:

• Always get the latest FlakeHub Cache release
• Occasionally participate in phased rollouts (helping us test new releases!)

Important

Set up Dependabot to stay current with FlakeHub Cache releases without sacrificing stability.

🤖 Automate updates with Dependabot

Keep your GitHub Actions fresh without manual work! Create .github/dependabot.yml with:

version: 2
updates:
  - package-ecosystem: github-actions
    directory: /
    schedule:
      interval: weekly

️⚙️ Configuration

Parameter	Description	Required	Default
use-gha-cache	Whether to upload build results to the Github Actions cache.
Set to "no-preference" or null to have the GitHub Actions cache turn on if it is available, and FlakeHub Cache is not available (default).
Set to "enabled" or true to explicitly request the GitHub Actions Cache.
Set to "disabled" or false to explicitly disable the GitHub Actions Cache.
flakehub-flake-name	The name of your flake on FlakeHub. The empty string will autodetect your FlakeHub flake.		``
diff-store	Whether or not to diff the store before and after Magic Nix Cache runs		False
startup-notification-port	The port magic-nix-cache uses for daemon startup notification.		41239
listen	The host and port to listen on.		127.0.0.1:37515
upstream-cache	Your preferred upstream cache. Store paths in this store will not be cached in GitHub Actions' cache.		https://cache.nixos.org
diagnostic-endpoint	Diagnostic endpoint url where diagnostics and performance data is sent. To disable set this to an empty string.		-
source-binary	Run a version of the cache binary from somewhere already on disk. Conflicts with all other source-* options.
source-branch	The branch of magic-nix-cache to use. Conflicts with all other source-* options.
source-pr	The PR of magic-nix-cache to use. Conflicts with all other source-* options.
source-revision	The revision of nix-magic-nix-cache to use. Conflicts with all other source-* options.		c79f1550609d4e9c4065a27fd599e76a94e0278d
source-tag	The tag of magic-nix-cache to use. Conflicts with all other source-* options.
source-url	A URL pointing to a magic-nix-cache binary. Overrides all other source-* options.
flakehub-cache-server	The FlakeHub binary cache server.		https://cache.flakehub.com
flakehub-api-server	The FlakeHub API server.		https://api.flakehub.com
_internal-strict-mode	Whether to fail when any errors are thrown. Used only to test the Action; do not set this in your own workflows.		False

🛟 Need help? We're here for you!

We're committed to making your experience with Determinate Nix and FlakeHub as smooth as possible. If you encounter any issues or have questions, here's how to reach us:

• 🐛 Found a bug? Open an issue on GitHub
• 💬 Want to chat? Join our Discord community for quick help and discussions
• 📧 Need direct support? Email us at [email protected]

🤝 Looking for enterprise support? We offer dedicated support contracts and shared Slack channels for organizations requiring priority assistance. Contact us to learn more.