Getting started

Push builds from CI to a Snowstead cache, then pull them on every machine instead of building them again. This takes about ten minutes.

1. Create a cache

Sign in to the dashboard and create a cache. Most teams start with one called main. Choose who can pull from it now: anyone, or only machines with a pull token. You can't change this once the cache has paths.

2. Create a push token

Under Tokens, create a token that can push to your cache. It's shown once, so copy it straight into your CI's secrets, for example as SNOWSTEAD_TOKEN. See Tokens for what each kind can do.

3. Push from CI

Install the CLI with Nix, sign in with the token, and push what you built along with everything it depends on:

nix profile install github:Polymath-AS/snowstead
snowstead login snowstead https://cache.snowstead.com "$SNOWSTEAD_TOKEN"
snowstead push main --closure ./result

The CLI only uploads what the cache doesn't already have, so pushing the same closure twice is quick. In GitHub Actions that looks like this:

- uses: DeterminateSystems/nix-installer-action@main
- run: nix build
- run: nix profile install github:Polymath-AS/snowstead
- run: snowstead login snowstead https://cache.snowstead.com "$SNOWSTEAD_TOKEN"
  env:
    SNOWSTEAD_TOKEN: ${{ secrets.SNOWSTEAD_TOKEN }}
- run: snowstead push main --closure ./result

4. Pull on every machine

Add the cache as a substituter, with its public key so Nix trusts what it downloads. Your cache's page in the dashboard has this snippet with its real URL and key filled in:

nix.settings = {
  substituters = [ "https://cache.snowstead.com/main" ];
  trusted-public-keys = [ "<the key from your cache's page>" ];
};

After a rebuild, Nix downloads anything your CI already pushed instead of building it. For a private cache, machines also need a pull token: see Private caches.

To change the key a cache signs with, use Signing key on its page: make a new key or import one you made with nix key generate-secret, add it to every machine's trusted-public-keys, then switch to it. Paths signed before keep their old signature, so keep trusting the old key too; the snippet on the cache's page lists every key.