nix-gitlab-ci/docs/caching.md

# Caching

Nix GitLab CI supports several caching mechanisms to speed up your pipelines.

## GitLab Runner Cache

The runner cache strategy copies the new store paths into a directory `.nix-cache`,
which is then saved in the regular GitLab cache (technically runner cache).
It's also configured as a substituter automatically.

To enable, set the cache strategy to `runner`.

Configure it using these environment variables:

- `RUNNER_CACHE`: path to the runner cache (default `.nix-cache`)

!!! warning

    This is very inefficient and should probably only be used for very very small
    dependency counts. Otherwise it takes an eternity to save to cache.

## Cachix

Cachix is a hosted binary cache service that can significantly speed up Nix
builds by sharing build results.

To enable, set the cache strategy to `attic`.

Configure it using these environment variables:

- `CACHIX_CACHE`: name of the cache to use
- (`CACHIX_AUTH_TOKEN`): cachix client itself uses this for authentication

!!! warning

    Cachix has not been tested. Feedback is appreciated :)

## Attic (Self-Hosted Cache)

Attic is a self-hosted, deduplicating binary cache. It's a great option if you
want more control over your caching infrastructure and to have the cache closer
to your runners.

To enable, set the cache strategy to `attic`.

Configure it using these environment variables:

- `ATTIC_SERVER`: URL of the server
- `ATTIC_CACHE`: name of the cache to use
- `ATTIC_TOKEN`: auth token from the attic server